NinjaOne MCP Server

A comprehensive Model Context Protocol (MCP) server that integrates NinjaOne RMM with Claude. Manage devices, automate IT tasks, handle ticketing, monitor patch status, and execute remote scripts—all through natural language conversation with Claude AI.

What is an MCP? A Model Context Protocol server extends Claude's capabilities by providing access to external systems and APIs. This server bridges Claude and NinjaOne, enabling AI-powered IT management.

✨ Key Features

🖥️ Device Management

• List, search, and get detailed information about devices

• Monitor device status, health, and connectivity

• Track active alerts and notifications

• Search devices using NinjaOne filter syntax

🚀 Device Actions

• Reboot devices (graceful or forced)

• Execute scripts and built-in actions remotely

• Automate IT tasks across your infrastructure

🔧 Patch & Software Management

• View OS and software patch status

• Track patch compliance

• Inventory installed software across devices

• Identify outdated or vulnerable software

🎫 Ticketing System

• Create support tickets programmatically

• Query existing tickets

• Update ticket information

• Add comments and notes

📊 Reporting & Monitoring

• Device health reports

• Antivirus status across fleet

• Organization-wide reporting

• Custom queries via generic API access

🔐 Enterprise Security

• OAuth 2.0 authentication with automatic token refresh

• No credentials in version control (environment variables only)

• Full support for NinjaOne's security model

• TypeScript for type safety

⚙️ Production Ready

• Node.js 20 LTS

• Comprehensive error handling

• Pagination support for large datasets

• 20+ API tools for complete NinjaOne integration

Related MCP server: datto-rmm-mcp

🚀 Quick Start

Prerequisites

• Node.js 20 LTS or higher (Download)

• npm (included with Node.js)

• NinjaOne account with API access

• Claude Desktop (for MCP integration)

Installation (5 minutes)

1. Clone the repository:

git clone https://github.com/SoroushAlamdari/ninjaone-mcp.git
cd ninjaone-mcp

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Configure NinjaOne credentials (see OAuth Setup below)

🔐 OAuth Setup (Required)

This server uses OAuth 2.0 client credentials flow for secure API access. Follow these steps:

Step 1: Create OAuth Application in NinjaOne

1. Log into your NinjaOne Dashboard

2. Go to Admin/Settings → API → Client app IDs

3. Click + Create application

4. Fill in the form:

   • Application platform: API Services (machine-to-machine)

   • Name: Claude MCP (or your preferred name)

   • Scopes: Check Monitoring, Management, Control

   • Allowed grant types: Check Client credentials

5. Click Create and copy the generated credentials

Step 2: Add Credentials to Environment

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your credentials:

NINJA_CLIENT_ID=<your_client_id_here>
NINJA_CLIENT_SECRET=<your_client_secret_here>
NINJA_API_BASE_URL=https://your-instance.ninjarmm.com

⚠️ Security: Never commit .env or token.json to version control. .gitignore covers both. Keep real values out of .env.example — it is committed.

How tokens are handled

• On start the server loads token.json if present, otherwise requests a token with client credentials.

• Before each API call it renews the token if it is within a minute of expiry, and if NinjaOne still answers 401 it renews once and retries.

• Every new token is saved to token.json, so restarts don't break the connection.

Alternative: browser login (Web app + refresh token)

If you can only use a Web client app, enable the Authorization code and Refresh token grants on it, then run once:

node get-oauth-token.js

Open the printed link, sign in, and the token (with refresh token) is saved to token.json. The script reads credentials from .env or from your Claude Desktop config. If NinjaOne answers Invalid scope offline_access, the app isn't allowed refresh tokens — use the API Services app above instead.

🤖 Claude Desktop Integration

Windows Setup

1. Edit Claude Desktop config:

   • Open: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json

   • Or use: %APPDATA%\Claude\claude_desktop_config.json

2. Add this to the mcpServers section:

{
  "mcpServers": {
    "ninjaone-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\ninjaone-mcp\\dist\\index.js"
      ],
      "env": {
        "NINJA_CLIENT_ID": "<your_client_id>",
        "NINJA_CLIENT_SECRET": "<your_client_secret>",
        "NINJA_API_BASE_URL": "https://your-instance.ninjarmm.com"
      }
    }
  }
}

macOS Setup

1. Edit Claude Desktop config:

   • Run: nano ~/.claude/claude_desktop_config.json

2. Add MCP configuration (same structure as Windows above, using macOS paths):

{
  "mcpServers": {
    "ninjaone-mcp": {
      "command": "node",
      "args": [
        "/Users/YourUsername/ninjaone-mcp/dist/index.js"
      ],
      "env": {
        "NINJA_CLIENT_ID": "<your_client_id>",
        "NINJA_CLIENT_SECRET": "<your_client_secret>",
        "NINJA_API_BASE_URL": "https://your-instance.ninjarmm.com"
      }
    }
  }
}

3. Start Using It

1. Close and reopen Claude Desktop

2. Look for the NinjaOne connector in the Connectors panel

3. Start using the tools:

   "List all my devices"
   "Show me critical alerts"
   "Get patch status for my servers"
   "Create a ticket for offline devices"
   "Run an inventory scan on all workstations"

Verification Checklist

• NinjaOne MCP appears in Claude Desktop Connectors list

• All 20+ tools are visible (no "no tools available" message)

• Test with: "List my devices"

• Devices appear in the response

📚 Available Tools (20+ API Functions)

Device Management (5 tools)

Device Actions (2 tools)

Patch Management (2 tools)

Software & Inventory (1 tool)

Ticketing (4 tools)

Organization & Contacts (3 tools)

Reports & Monitoring (2 tools)

Advanced/Generic API (2 tools)

💬 Example Use Cases

Ask Claude any of these:

"List all my devices and show their status"
"Which devices haven't checked in for more than 24 hours?"
"Show me all critical and high-severity alerts"
"Get patch compliance report for all Windows servers"
"Create a ticket for all offline devices"
"Search for all devices with antivirus disabled"
"Run a compliance script on all workstations in Location XYZ"
"Show me devices running outdated versions of software"
"Get a summary of device health across the organization"
"Which devices need OS updates?"

📡 API Methods & Endpoints

All tools communicate with NinjaOne API v2.0 using the following base URL:

https://<your-instance>.ninjarmm.com/api/v2

Authentication Header

All requests include:

Authorization: Bearer <access_token>
Content-Type: application/json

Tool Reference with API Methods

Example API Calls

List Devices (with pagination):

curl -X GET "https://your-instance.ninjarmm.com/api/v2/devices?pageNo=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Get Device Details:

curl -X GET "https://your-instance.ninjarmm.com/api/v2/devices/12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search Devices with Filter:

curl -X GET "https://your-instance.ninjarmm.com/api/v2/devices?filter=status=online" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Create a Ticket:

curl -X POST "https://your-instance.ninjarmm.com/api/v2/tickets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Device Offline",
    "description": "Device XYZ is offline",
    "priority": "high"
  }'

Reboot a Device:

curl -X POST "https://your-instance.ninjarmm.com/api/v2/devices/12345/reboot" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "graceful"}'

NinjaOne API Documentation

For complete API reference and additional endpoints:

• Main API Docs: https://app.ninjarmm.com/apidocs

• Beta API: https://app.ninjarmm.com/apidocs-beta/core-resources

• Authorization: https://app.ninjarmm.com/apidocs-beta/authorization/overview

🛠️ Development

Build Production Code

npm run build

Watch Mode (Auto-rebuild on changes)

npm run dev

Type Checking

npm run type-check

Run Tests

npm test

Project Structure

ninjaone-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── api-client.ts      # NinjaOne API wrapper
│   ├── oauth.ts           # OAuth 2.0 handling
│   ├── tools.ts           # Tool definitions
│   └── types.ts           # TypeScript interfaces
├── dist/                  # Compiled JavaScript (auto-generated)
├── package.json
├── tsconfig.json
└── README.md

🔒 Security Best Practices

✅ Do:

• ✅ Use .env file for credentials (already in .gitignore)

• ✅ Rotate OAuth credentials regularly

• ✅ Limit API scopes to what you need

• ✅ Use strong, unique client secrets

• ✅ Monitor API usage in NinjaOne

❌ Don't:

• ❌ Commit .env file to version control

• ❌ Share credentials or secrets

• ❌ Use credentials in code or logs

• ❌ Store secrets in comments

• ❌ Log sensitive information

🐛 Troubleshooting

"NinjaOne MCP connector not appearing in Claude Desktop"

• Verify dist/index.js exists: ls dist/

• Rebuild: npm run build

• Check JSON syntax: Use jsonlint.com

• Close and fully reopen Claude Desktop (don't just restart)

• Check file paths match your installation

"Invalid or missing credentials"

• Verify credentials in .env file (not in config file)

• Check for extra spaces or quotes in values

• Regenerate credentials in NinjaOne if unsure

• Ensure API application has correct scopes: Monitoring, Management, Control

"Cannot find module errors"

• Run: npm install

• Delete node_modules folder and reinstall: rm -rf node_modules && npm install

"node: command not found"

• Verify Node.js 20+ is installed: node --version

• On Windows, use full path or add Node to PATH

• On macOS/Linux, ensure /usr/local/bin is in PATH

Enable Debug Logging

Set environment variable and rebuild:

export DEBUG=1    # Linux/macOS
set DEBUG=1       # Windows
npm run build

📖 API Documentation

For detailed NinjaOne API documentation:

• NinjaOne API Docs

• API Reference

📄 License

MIT License - See LICENSE file for details

Free to use, modify, and distribute.

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Test your changes

4. Submit a pull request

💡 Support

• Issues: Use GitHub Issues

• API Help: NinjaOne Support

• MCP Spec: Model Context Protocol

📊 Project Stats

• Language: TypeScript

• Runtime: Node.js 20 LTS

• API Integration: NinjaOne RMM v2.0

• Protocol: Model Context Protocol (MCP)

• Authentication: OAuth 2.0

• Tools: 20+