# NinjaOne MCP

A local [Model Context Protocol](https://modelcontextprotocol.io) server for [NinjaOne](https://www.ninjaone.com/) ticketing. It lets any MCP client (Claude Desktop, Claude Code, and others) search, read, create, update, and comment on NinjaOne tickets.

Runs locally over stdio using your own NinjaOne OAuth credentials. No third-party service sits in the middle.

## Tools

| Tool | Description |
|------|-------------|
| `search_tickets` | List tickets from a board (paginated) |
| `get_ticket` | Get a single ticket by ID |
| `create_ticket` | Create a ticket |
| `update_ticket` | Update a ticket (status, priority, severity, assignee, subject) |
| `add_comment` | Add a public response or private note to a ticket |
| `list_statuses` | List ticket statuses with IDs |
| `list_organizations` | List organizations (clients) |
| `list_technicians` | List technicians with their numeric IDs |
| `list_boards` | Return the default board ID |
| `get_auth_url` / `exchange_code` | Manual OAuth flow to obtain a user refresh token |

## Prerequisites

- Node.js 18+
- A NinjaOne API OAuth client (NinjaOne > **Administration > Apps > API**):
  - **Client ID** and **Client Secret**
  - Scopes: `monitoring` (reads) and `management` (ticket writes)
  - For user-context writes (comments authored as you), enable the **Authorization Code** grant and the `offline_access` scope, and register a redirect URI (`http://localhost:3846/` for the built-in flow, or `https://localhost` if you use `get-refresh-token.js`).

## Install

```bash
git clone https://github.com/cyberkoder/ninjaone-mcp.git
cd ninjaone-mcp
npm install
```

## Configuration

All configuration is via environment variables (see [`.env.example`](.env.example)):

| Variable | Required | Notes |
|----------|----------|-------|
| `NINJA_BASE_URL` | yes | Your region's host, e.g. `https://app.ninjarmm.com` (US), `https://eu.ninjarmm.com` (EU) |
| `NINJA_CLIENT_ID` | yes | OAuth client ID |
| `NINJA_CLIENT_SECRET` | yes | OAuth client secret |
| `NINJA_SCOPE` | no | Defaults to `monitoring management control` |
| `NINJA_REFRESH_TOKEN` | for writes | User-context refresh token (preferred). See below. |
| `NINJA_SESSION_KEY` | alt | NinjaOne web session cookie value (expires with the browser session) |
| `NINJA_DEFAULT_CLIENT_ID` | no | Default org ID for `create_ticket` |
| `NINJA_LOCAL_AUTH_PORT` | no | Port for the one-time interactive login (default `3846`) |

Reads (`search_tickets`, `get_ticket`, list tools) work with just the client ID/secret via `client_credentials`. Writes require user context (a refresh token or session key). If neither is set, the first write opens a browser once to authenticate you and captures a refresh token for the session.

### Getting a refresh token

```bash
NINJA_CLIENT_ID=... NINJA_CLIENT_SECRET=... node get-refresh-token.js
```

Follow the prompts, then set the printed value as `NINJA_REFRESH_TOKEN`.

## MCP client setup

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ninjaone": {
      "command": "node",
      "args": ["/absolute/path/to/ninjaone-mcp/index.js"],
      "env": {
        "NINJA_BASE_URL": "https://app.ninjarmm.com",
        "NINJA_CLIENT_ID": "your-client-id",
        "NINJA_CLIENT_SECRET": "your-client-secret",
        "NINJA_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add ninjaone -- node /absolute/path/to/ninjaone-mcp/index.js
```

Then set the `NINJA_*` environment variables for the server (via the config file's `env` block or your shell).

## Known limitations

These reflect how NinjaOne's ticketing API actually behaves, so you know what to expect:

- **Reads vs. writes need different auth.** `client_credentials` (client ID + secret) is read-only. Creating, updating, or commenting on tickets requires *user context* - a refresh token, a session key, or the one-time browser login. With reads-only auth, write tools return an auth error.
- **Authorization Code grant must be enabled.** Older NinjaOne OAuth clients only expose the "Refresh Token" grant and return `unauthorized_client` for the authorization-code flow. Enable Authorization Code (and the `offline_access` scope) on the API client, or the interactive/`get-refresh-token.js` flows won't work.
- **Comments must be `multipart/form-data`.** The `/comment` endpoint rejects `application/json` with HTTP 415. This server already posts the correct form encoding - noted so forks don't regress it.
- **Refresh tokens rotate.** NinjaOne may issue a new refresh token on use. The server logs the rotated value to stderr, but it only persists for the process lifetime - copy it back into `NINJA_REFRESH_TOKEN` to keep it across restarts.
- **Session keys are short-lived.** `NINJA_SESSION_KEY` is a browser-session cookie and expires when that session ends. Prefer a refresh token for anything long-running.
- **`update_ticket` is read-modify-write.** It fetches the ticket first to supply the required `version` and `requesterUid`, so concurrent edits can hit optimistic-locking conflicts. Some status transitions (e.g. directly to a closed state) are restricted by NinjaOne's workflow.
- **Interactive login is local-only.** The automatic browser flow needs a localhost redirect and a desktop browser; it won't work in headless/CI environments (use a pre-obtained `NINJA_REFRESH_TOKEN` there).
- **No "list boards" API.** NinjaOne doesn't expose one; board `1` is the default. Use `list_organizations` and `list_technicians` to discover IDs.
- **No built-in rate-limit handling or retries**, and the toolset is intentionally scoped to core ticketing (no attachments, custom fields, time entries, or asset/monitoring endpoints yet). PRs welcome.

This is an independent open-source project and is not affiliated with or endorsed by NinjaOne.

## License

MIT