NinjaOne MCP 服务器

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

一键部署

[!IMPORTANT] 点击之前请注意： 此服务器依赖 @wyre-technology/node-ninjaone， 该包托管在 GitHub Packages npm 注册表上。GitHub Packages 没有 匿名访问——即使包是公开的，每次 npm install 都需要一个令牌。 云构建器会为你运行 npm install，因此你必须提供一个令牌，否则 构建会失败并显示 npm error 401 Unauthorized ... npm.pkg.github.com。

1. 创建一个具有 read:packages 范围的 GitHub 个人访问令牌 （经典令牌）。 任何 GitHub 账户都可以——你不需要是 wyre-technology 组织的成员 即可读取其公共包。

2. 在部署流程提示时将其添加为构建变量：

   • Cloudflare Workers → 将名为 NODE_AUTH_TOKEN 的构建变量设置为你的 PAT （Workers → Settings → Build → Variables and Secrets）。

   • DigitalOcean App Platform → 将名为 GITHUB_TOKEN 的加密环境变量 设置为你的 PAT，作用域为 Build Time（.do/app.yaml 已声明该变量）。

[!NOTE] 两个目标都运行完整的 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-* 请求头 按请求获取凭据。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-technology/ninjaone-mcp

仓库的 .npmrc 已将 @wyre-technology 范围指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌， 因此无需进一步配置。下面的 npx @wyre-technology/ninjaone-mcp 也是如此。想要零设置选项？ 使用预构建的容器镜像（ghcr.io/wyre-technology/ninjaone-mcp）或每个 发布 附带的 .mcpb 捆绑包。

配置

设置以下环境变量：

NinjaOne API 区域

用法

独立运行

# 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-technology/ninjaone-mcp

Claude Desktop 配置

添加到你的 Claude Desktop claude_desktop_config.json：

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

Docker

docker build -t ninjaone-mcp .
docker run -e NINJAONE_CLIENT_ID=xxx -e NINJAONE_CLIENT_SECRET=xxx -e NINJAONE_REGION=us ninjaone-mcp

可用域

设备

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

工具：

• ninjaone_devices_list - 列出设备，可按组织、设备类别和在线状态筛选。分页：完整页面返回 hasMore: true 和用于下一页的 cursor。

• ninjaone_devices_get - 获取设备详细信息

• ninjaone_devices_reboot - 安排设备重启

• ninjaone_devices_services - 列出设备上的 Windows 服务

• ninjaone_devices_alerts - 获取特定于设备的警报

• ninjaone_devices_activities - 查看设备活动日志

组织

管理客户组织及其资源。

工具：

• ninjaone_organizations_list - 列出组织

• ninjaone_organizations_get - 获取组织详细信息

• ninjaone_organizations_create - 创建新组织

• ninjaone_organizations_locations - 列出组织位置

• ninjaone_organizations_devices - 列出组织的设备

警报

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

工具：

• 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 - 创建新工单

• ninjaone_tickets_update - 更新现有工单

• ninjaone_tickets_add_comment - 向工单添加评论

• ninjaone_tickets_comments - 获取工单评论

• ninjaone_tickets_boards_list - 列出工单看板（以发现 board_id 值）

注意： NinjaOne 按看板查询工单，且看板 ID 因租户而异—— 看板 1 并不总是“所有工单”看板，因此 ninjaone_tickets_list 需要显式的 board_id，而不是静默猜测一个。使用 ninjaone_tickets_boards_list 发现 ID；在端点返回 404 的租户上，从 NinjaOne Web UI 中看板链接的 URL 读取数字 ID （例如“所有工单”侧边栏链接）。

注意： NinjaOne 的看板运行 API 无法按状态、组织或设备在服务器端筛选工单 （尝试会抛出通用的 Bad request）。因此 ninjaone_tickets_list 在单个看板页面内 客户端应用这些筛选器。响应将 count（此页面中的匹配数）与 scanned（已检查的工单数）分开， 并包含 hasMore/cursor——翻页直到 hasMore 为 false 以获取所有匹配项， 切勿将单页的 count 视为整个看板的总数。状态与每个工单的状态显示名称匹配， 因此自定义看板状态可能无法映射到 OPEN/IN_PROGRESS/WAITING/CLOSED 值。

类似地，ninjaone_devices_list 通过 NinjaOne 专用的按组织端点按 organization_id 筛选 （通用的 df=org 设备筛选器不可靠，可能静默返回整个设备群）。

导航工具

始终可用：

• 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. 记下客户端 ID 和客户端密钥

6. 配置环境变量

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

OAuth 范围

默认情况下，服务器请求 monitoring management。你实际需要的范围取决于你的用途：

如果你的 API 应用被授予的范围少于默认值，请将 NINJAONE_SCOPES 设置为匹配。 NinjaOne 会拒绝请求应用从未被授予的范围的令牌请求——它返回 400 invalid_scope 而不是缩小授权—— 因此失败发生在令牌交换时，每个工具调用都会失败，包括读取。对于仅监控的应用：

export NINJAONE_SCOPES="monitoring"

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

许可证

Apache-2.0