NinjaOne

NinjaOne MCP 服务

一个用于与 NinjaOne 交互的模型上下文协议（MCP）服务，采用决策树架构，以高效加载工具。

一键部署

重要

**点击前请注意：**此服务依赖 @wyre-ai/node-ninjaone， 该软件包托管在 GitHub Packages npm 注册表中。GitHub Packages 不支持 匿名访问——即使软件包是公开的，每次 npm install 仍需要令牌。云端构建器会为你运行 npm install，因此你必须向它提供令牌，否则构建会失败，并显示 npm error 401 Unauthorized ... npm.pkg.github.com。

1. 创建一个具有 read:packages 范围的 GitHub Personal Access Token （classic token）。 任何 GitHub 账户都可以——你无需成为 wyre-ai 组织的成员， 即可读取其公开软件包。
2. 部署流程提示时，将令牌添加为构建变量：
   • Cloudflare Workers → 设置名为 NODE_AUTH_TOKEN 的构建变量，并将其值设为你的 PAT （Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → 设置名为 GITHUB_TOKEN 的加密环境变量， 将范围设为 Build Time，并将其值设为你的 PAT（.do/app.yaml 已声明该变量）。

说明

两种目标都会运行完整的 MCP 服务。DigitalOcean 会构建 Docker 镜像并 通过 HTTP 提供服务；Cloudflare Workers 则通过 SDK 的 Web Standard Streamable HTTP 传输方式提供同一服务（src/worker.ts）。部署后，将你的 NinjaOne 凭据设置为密钥——NINJAONE_CLIENT_ID、NINJAONE_CLIENT_SECRET 和可选的 NINJAONE_REGION——或者设置 AUTH_MODE=gateway，通过 X-Ninja-* 标头 按请求提供凭据。HTTP 还需要 CONDUIT_S2S_SECRET，并且 /mcp 上必须有有效的 X-Gateway-S2S 签名（参见 HTTP 身份验证）。 MCP 端点为 /mcp；/health 是无需身份验证的存活探测端点。

架构

此 MCP 服务采用分层工具加载方式，而不是一开始就公开所有工具：

1. 导航阶段：最初只公开一个导航工具（ninjaone_navigate）
2. 选择领域：用户选择一个领域（设备、组织、警报、工单）
3. 领域工具：选择后，服务公开该领域专属的工具
4. 延迟加载：按需加载领域处理程序和 NinjaOne 客户端

此架构具有以下优点：

• 降低认知负担（可选工具更少）
• 缩短初始加载时间
• 更好地组织相关操作
• 导航状态清晰

安装

此软件包发布在 GitHub Packages npm 注册表中，即使是公开软件包也需要令牌。 完成一次身份验证后即可安装：

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/ninjaone-mcp

仓库的 .npmrc 已将 @wyre-ai 作用域指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌，因此无需进一步配置。下文中的 npx @wyre-ai/ninjaone-mcp 也适用同样的设置。想要零配置选项？请使用预构建的 容器镜像（ghcr.io/wyre-ai/ninjaone-mcp），或使用每个版本附带的 .mcpb 包。

配置

复制 .env.example，并设置以下变量。

变量	必填	描述
NINJAONE_CLIENT_ID	用于 stdio 和 AUTH_MODE=env	OAuth 2.0 客户端 ID
NINJAONE_CLIENT_SECRET	用于 stdio 和 AUTH_MODE=env	OAuth 2.0 客户端密钥
NINJAONE_REGION	否	区域：us（默认）、eu、oc、ca、us2 或 fed
NINJAONE_SCOPES	否	要请求的 OAuth 范围。默认为 monitoring,management。如果授予 API 应用的范围较窄，请设置此项 — 参见 OAuth 范围
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认值）或 env。Gateway 模式要求每个 /mcp 请求都提供 X-Ninja-Client-ID 和 X-Ninja-Client-Secret，且绝不会回退到 NINJAONE_*。env 仅在 S2S 身份验证成功后使用这些变量。
CONDUIT_S2S_SECRET	HTTP 必填	服务间密钥。如果该值为空或是已知占位符，HTTP 服务会记录错误并以非零状态码退出。未设置此项时，Compose 不会启动。切勿提交真实值。使用 openssl rand -hex 32 生成密钥。
MCP_ALLOW_INSECURE_DEV	否	仅用于本地开发时，准确设置为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制执行 X-Gateway-S2S，且只绑定到 127.0.0.1。已知占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。仅在设置了 CONDUIT_S2S_SECRET 时生效。容器镜像将其设为 0.0.0.0。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含：

X-Gateway-S2S: t=<unix seconds>,v1=<hex>

v1 是对 ASCII 字符串 t=<unix seconds>（与请求头中发送的 t= 前缀相同）进行 HMAC-SHA256 运算的结果，使用 CONDUIT_S2S_SECRET 作为密钥，并以十六进制编码。时间戳与服务器时钟的差值不得超过 300 秒。缺少请求头或请求头无效时，会在读取任何供应商凭据之前返回 401。密钥值绝不会写入日志。

在 AUTH_MODE=gateway 下，/mcp 还需要 X-Ninja-Client-ID 和 X-Ninja-Client-Secret（X-Ninja-Region 为可选项）。这些请求头是该请求唯一的凭据来源。请求缺少这些请求头时会返回 401，且不会回退到 NINJAONE_CLIENT_ID / NINJAONE_CLIENT_SECRET。

MCP_ALLOW_INSECURE_DEV=1 会跳过本地开发时的 X-Gateway-S2S 检查，并强制监听器绑定到 127.0.0.1。此模式下会忽略非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0），并记录此覆盖操作。

NinjaOne API 区域

区域	基础 URL
us	https://app.ninjarmm.com
eu	https://eu.ninjarmm.com
oc	https://oc.ninjarmm.com
ca	https://ca.ninjarmm.com
us2	https://us2.ninjarmm.com
fed	https://fed.ninjarmm.com

使用方法

独立运行

# Set credentials
export NINJAONE_CLIENT_ID="your-client-id"
export NINJAONE_CLIENT_SECRET="your-client-secret"
export NINJAONE_REGION="us"

# Run the server
npx @wyre-ai/ninjaone-mcp

Claude Desktop 配置

将以下内容添加到 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "ninjaone": {
      "command": "npx",
      "args": ["@wyre-ai/ninjaone-mcp"],
      "env": {
        "NINJAONE_CLIENT_ID": "your-client-id",
        "NINJAONE_CLIENT_SECRET": "your-client-secret",
        "NINJAONE_REGION": "us"
      }
    }
  }
}

Docker

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到环回地址，并传入 S2S 密钥。在 gateway 模式下，每个请求都会通过 X-Ninja-* 标头传入 NinjaOne 凭据；不会从环境变量中读取这些凭据。

docker build -t ninjaone-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  ninjaone-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；默认将 AUTH_MODE 设为 gateway，发布 127.0.0.1:8080:8080，且不会注入 NINJAONE_CLIENT_ID 或 NINJAONE_CLIENT_SECRET：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，随后使用 NINJAONE_CLIENT_ID 和 NINJAONE_CLIENT_SECRET：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e NINJAONE_CLIENT_ID=your-client-id \
  -e NINJAONE_CLIENT_SECRET=your-client-secret \
  -e NINJAONE_REGION=us \
  -p 127.0.0.1:8080:8080 \
  ninjaone-mcp

不使用密钥的本地 HTTP 仅供开发使用。它只绑定到 127.0.0.1，并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

按照HTTP 身份验证中的说明，使用 X-Gateway-S2S 为每个 /mcp 请求签名。在 gateway 模式下，还需发送 X-Ninja-Client-ID 和 X-Ninja-Client-Secret。

可用领域

设备

管理终端、重启设备、查看服务和警报。

工具：

• ninjaone_devices_list - 列出设备，可按组织、设备类别和在线状态筛选。支持分页：如果返回完整页面，则 hasMore: true，并提供一个 cursor，供下一页请求使用。
• ninjaone_devices_get - 获取设备详情
• ninjaone_devices_reboot - 安排设备重启
• ninjaone_devices_services - 列出设备上的 Windows 服务
• ninjaone_devices_alerts - 获取设备专属警报
• ninjaone_devices_activities - 查看设备活动日志
• ninjaone_devices_get_custom_fields - 获取设备自定义字段
• ninjaone_devices_update_custom_fields - 更新设备自定义字段

组织

管理客户组织及其资源。

工具：

• ninjaone_organizations_list - 列出组织
• ninjaone_organizations_get - 获取组织详情
• ninjaone_organizations_create - 创建新组织
• ninjaone_organizations_locations - 列出组织地点
• ninjaone_organizations_devices - 列出组织的设备。device_class 会以 df=class=<NodeClass> 的形式发送到上游，并应用于每一页。响应为 { devices, count, hasMore, cursor }，而不是纯数组。
• ninjaone_organizations_get_custom_fields - 获取组织自定义字段
• ninjaone_organizations_update_custom_fields - 更新组织自定义字段

警报

查看和管理所有设备的警报。

工具：

• ninjaone_alerts_list - 按筛选条件列出警报
• ninjaone_alerts_get - 按 UID 获取单条警报（在 MCP Apps 宿主中呈现为交互式卡片）
• ninjaone_alerts_reset - 重置／关闭单条警报
• ninjaone_alerts_reset_all - 重置设备或组织的所有警报
• ninjaone_alerts_summary - 获取警报数量摘要

功能：

• 交互式警报卡片（MCP Apps，SEP-1865）：ninjaone_alerts_get 在 MCP Apps 宿主（Claude Desktop/web）中呈现为交互式卡片，可通过 ninjaone_alerts_reset 在卡片内完成“重置警报”的往返操作；默认采用中性色，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量进行品牌定制；在其他宿主中的纯 JSON 行为保持不变

工单

管理服务工单。

工具：

• ninjaone_tickets_list - 列出工单板中的工单（需要 board_id；status/organization_id/device_id 筛选在客户端执行，详见下方说明）
• ninjaone_tickets_get - 获取工单详情
• ninjaone_tickets_create - 创建新工单（需要 ticket_form_id）
• ninjaone_tickets_update - 更新现有工单的字段
• ninjaone_tickets_add_comment - 为工单添加评论
• ninjaone_tickets_comments - 获取工单日志条目，可按 type 筛选
• ninjaone_tickets_boards_list - 列出工单板（用于查找 board_id 值）
• ninjaone_tickets_forms_list - 列出工单表单（用于查找 ticket_form_id 值）
• ninjaone_tickets_form_get - 获取一个工单表单及其字段定义
• ninjaone_tickets_statuses_list - 列出租户配置的工单状态
• ninjaone_tickets_attributes_list - 列出工单属性（自定义字段）定义
• ninjaone_tickets_contacts_list - 列出工单联系人（用于 requester_uid）
• ninjaone_tickets_users_list - 列出技术人员、最终用户和联系人（用于 assignee_id）

注意： NinjaOne 按工单板查询工单，且工单板 ID 因租户而异—— 工单板 1 并不总是“所有工单”板，因此 ninjaone_tickets_list 需要明确指定 board_id，而不是默默猜测。使用 ninjaone_tickets_boards_list 查找 ID。

注意： 工单状态、表单和属性均由租户配置。 请使用 ninjaone_tickets_statuses_list、 ninjaone_tickets_forms_list 和 ninjaone_tickets_attributes_list 读取实际 ID，而不要假定名称固定。priority 的值为 NONE/LOW/MEDIUM/HIGH—— CRITICAL 属于 severity，而非优先级。

注意： NinjaOne 的工单板查询 API 无法在服务端按状态、 组织或设备筛选工单（尝试这样做会返回通用的 Bad request）。因此，ninjaone_tickets_list 会在单个工单板页面内 于客户端执行这些筛选。响应会分别提供 count（本页匹配数） 和 scanned（检查的工单数），并包含 hasMore/cursor — 翻页直到 hasMore 为 false，以获取所有匹配项；切勿将 单页的 count 视为工单板总数。状态按每张 工单的状态显示名称进行匹配，因此请传入租户实际使用的名称 — ninjaone_tickets_statuses_list 会列出这些名称。

同样，ninjaone_devices_list 会通过 NinjaOne 专用的按组织查询端点按 organization_id 筛选设备（通用的 df=org 设备 筛选不可靠，可能会在不提示的情况下返回整个设备群）。该端点 未记录任何设备类别查询参数。ninjaone_devices_list （设置了组织时）和 ninjaone_organizations_devices 仍会将 device_class 作为 df=class=<NodeClass> 发送到上游（命名参数 nodeClass 会被忽略），并对每一页应用类别和在线状态筛选。count 表示本页匹配数；只要 hasMore 为 true，就继续翻页。device_class 使用 NinjaOne 节点类别 （LINUX_WORKSTATION、VMWARE_VM_HOST、NMS_SWITCH，等等）— LINUX、 VMWARE_VM 和 NMS 均无效。

导航工具

始终可用：

• ninjaone_navigate - 选择要使用的领域
• ninjaone_status - 显示当前状态和凭据状态
• ninjaone_back - 返回主菜单（在某个领域中时）

工作流示例

User: Check my devices
Claude: [calls ninjaone_navigate with domain="devices"]
       -> Navigated to devices domain. Available tools: ...

User: List all Windows servers
Claude: [calls ninjaone_devices_list with device_class="WINDOWS_SERVER"]
       -> [device list results]

User: Now show me alerts
Claude: [calls ninjaone_back]
       -> Navigated back to main menu.
       [calls ninjaone_navigate with domain="alerts"]
       -> Navigated to alerts domain.

身份验证

NinjaOne 使用 OAuth 2.0 进行身份验证。你需要：

1. 登录 NinjaOne 仪表板
2. 前往 Administration > Apps > API
3. 创建新的 API 应用（应用平台：API Services，授权类型：Client Credentials）
4. 授予所需的作用域 — 见下文
5. 记下 Client ID 和 Client Secret
6. 配置环境变量

客户端库会自动处理令牌刷新。

OAuth 权限范围

默认情况下，服务器会请求 monitoring management。实际需要哪些权限范围取决于你的使用方式：

权限范围	用途
monitoring	所有读取操作——列出设备、组织、警报和工单
management	写入操作——重启设备、重置警报、创建或更新工单和组织
control	此服务器不会使用

如果你的 API 应用获得的权限范围少于默认值，请设置 NINJAONE_SCOPES 使其与之匹配。 NinjaOne 会拒绝请求应用未获授权的权限范围的令牌请求——它会返回 400 invalid_scope，而不是缩小授权范围——因此故障会发生在令牌交换阶段， 所有工具调用都会失败，包括读取操作。对于仅有 monitoring 权限的应用：

export NINJAONE_SCOPES="monitoring"

值可以用逗号或空格分隔，且不区分大小写。在网关部署中，也可以通过 X-Ninja-Scopes 请求头为每个请求提供相同的值。

许可证

Apache-2.0