ninjaone-mcp

NinjaOne RMM MCP 服务器——将 NinjaOne 公共 API v2(组织、设备、告警、工单、自动化/脚本、任务)以 MCP 工具的形式暴露出来。

什么是 NinjaOne / 代理在什么情况下会使用它

NinjaOne 是一个 RMM(远程监控和管理)平台,MSP 用它来管理客户的 IT 设备群。当出现以下请求时,代理应使用此 MCP:

• "这个客户有多少台设备,哪些处于离线状态?" → ninjaone_get_organization_devices / ninjaone_get_devices

• "这个设备/组织有活跃告警吗?" → ninjaone_get_device_alerts / ninjaone_get_alerts

• "支持看板上有哪些未关闭的工单?" → ninjaone_get_ticket_boards,然后 ninjaone_get_tickets

• "在这台设备上运行磁盘清理,完成后告诉我" → 使用 ninjaone_get_device_scripting_options 确认可运行内容,ninjaone_run_script_on_device 执行,然后通过 ninjaone_get_device_active_jobs 监控完成情况

• "我们有哪些可用的自动化脚本?" → ninjaone_get_automation_scripts

概述

该服务器实现了模型上下文协议(Streamable HTTP 传输),包含 5 组共 23 个工具,遵循 MSPbots 供应商 MCP 服务 SOP:无状态、不存储凭据、按请求进行 Header 认证。

本项目基于社区 wyre-technology/ninjaone-mcp 项目的工具面(组织/设备/告警/工单,此处直接针对 NinjaOne 的 REST API 而非其 Node SDK 重新实现)构建,并扩展了 5 个来自 NinjaOne 自身 OpenAPI 3.0.1 规范的自动化/脚本/任务工具——以下每个端点都对照真实的 NinjaOne API 规范进行了验证,而非猜测或从二手来源复制。

NinjaOne 通过 OAuth2 client_credentials 进行身份验证:在 POST {base_url}/oauth/token 处,使用 NinjaOne "API Services" OAuth2 应用的客户端 ID + 密钥交换短期 bearer 令牌。该服务器自行完成此交换,每次工具调用都会重新获取——它从不在调用之间存储或缓存令牌(或 client_id/secret)。

快速开始

Docker(推荐)

docker compose up --build

服务器启动在 http://localhost:8080。

本地(uv)

uv sync
python -m ninjaone_mcp

健康检查

curl http://localhost:8080/health
# {"status": "ok"}

健康检查端点不需要凭据。

授权参数说明 (Authentication)

对 /mcp 的每个请求都必须包含以下 HTTP 请求头:

缺少任一必需 Header 将返回 401 Unauthorized。

环境变量

没有 base-URL 环境变量——base URL 根据 X-Ninja-Region 请求头按请求派生(参见 config.py 的区域表)。

MCP 端点

POST http://localhost:8080/mcp

使用以下方式连接你的 MCP 客户端:

• 传输方式:http(Streamable HTTP)

• 请求头:X-Ninja-Client-Id、X-Ninja-Client-Secret(均必填)、X-Ninja-Region(可选)

工具列表

测试示例 (Test Example)

列出工单看板:

{
  "method": "tools/call",
  "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
}

针对运行中的服务器执行等效的 curl(streamable HTTP MCP 端点):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Ninja-Client-Id: <client_id>" \
  -H "X-Ninja-Client-Secret: <client_secret>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
  }'

在设备上运行脚本:

{
  "method": "tools/call",
  "params": {
    "name": "ninjaone_run_script_on_device",
    "arguments": { "device_id": 123, "type": "SCRIPT", "script_id": 456 }
  }
}

API 参考

• 文档:https://app.ninjarmm.com/apidocs-beta/core-resources(eu/oc/ca/us2/fed 区域有对应版本)

• 认证:在 POST /oauth/token 处使用 OAuth2 client_credentials 授权(grant_type、client_id、client_secret、scope),作用域:monitoring、management、control

已知差距 / 实现说明

• 端点来源：5 个自动化/脚本/作业端点中的 4 个（requestScriptingOptions、runScriptOnDevice、getActiveJobs、getDeviceActiveJobs）已与独立获取的 NinjaOne OpenAPI 规范副本进行了交叉核对。该副本中不存在 getAutomationScripts（它比该规范修订版更新）——其确切的 /api 路径位置是根据其他 4 个已确认的模式推断出来的，并非独立验证。请参阅 tools/automation.py 顶部的注释。

• ninjaone_get_tickets 在客户端侧过滤：NinjaOne 的运行看板端点的请求 schema 定义了 filters/searchCriteria 参数，但社区 wyre-technology 项目报告这些参数在实践中会返回 400——此工具始终请求未过滤的页面，并在客户端侧过滤 status/organization_id/device_id。

• 没有单张工单获取或独立添加评论的端点：NinjaOne 的工单 API 不提供 GET /ticketing/ticket/{id}——要查找单张工单，需要在其看板上分页遍历 ninjaone_get_tickets。添加评论也不是独立的端点——它被合并到 ninjaone_update_ticket 的 comment/comment_public 参数中，同时还会对工单本身执行 PUT。

• ninjaone_get_devices 的 df 过滤器在按组织限定范围时可能被 NinjaOne 静默丢弃（社区项目中的一个已知问题）——对于按组织限定的设备列表，请优先使用 ninjaone_get_organization_devices。

• 尚未使用真实凭据对真实 NinjaOne 账户进行测试——目前已验证：tools/list 返回全部 23 个工具且 schema 干净，pytest（15 个测试）通过，并且使用虚拟 client_id/secret 进行的实时调用到达了 NinjaOne 真实的生产环境 /oauth/token 端点，并收到了真实且格式正确的拒绝（Client app not exist），而不是格式错误的请求错误——这确认了基础 URL、令牌端点和请求格式都是正确的。