内容
# 忍者一体 MCP 服务器
一个适用于 [忍者一体 RMM 平台](https://www.ninjaone.com) 的 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器。 为 Claude 和其他 MCP 客户端提供直接访问您的忍者一体环境的权限 — 查询设备、管理警报、运行脚本、创建工单等。
## 功能
- **75 种工具**，涵盖所有主要的忍者一体 API 领域
- 使用自动令牌刷新的 OAuth2 `client_credentials` 身份验证
- 所有列表端点支持分页和设备筛选 (`df`)
- 除了 `axios` 和 MCP SDK 之外，没有运行时依赖
## 先决条件
- [Node.js](https://nodejs.org) 18 或更高版本
- 具有 API 访问权限的忍者一体账户
- OAuth2 API 凭证（参见 [获取凭证](#获取凭证)）
## 获取凭证
1. 登录到您的忍者一体门户并前往 **管理 → 应用 → API**
2. 点击 **添加** 以创建新的 API 应用程序
3. 选择 **客户端凭证** 作为授权流程
4. 授予您的用例所需的范围：
- `monitoring` — 只读设备/警报数据
- `management` — 管理设备、组织、策略
- `control` — 运行脚本、触发补丁作业、重启设备
5. 复制 **客户端 ID** 和 **客户端密钥** — 密钥仅显示一次
您的实例基本 URL 取决于您的区域：
| 区域 | 基本 URL |
|--------|----------|
| 美国 | `https://app.ninjarmm.com` |
| 欧洲 | `https://eu.ninjarmm.com` |
| 大洋洲 | `https://oc.ninjarmm.com` |
| 加拿大 | `https://ca.ninjarmm.com` |
## 安装
### 选项 1 — 克隆和构建（推荐）
```bash
git clone https://github.com/Allied-Business-Solutions/ninjaone-mcp.git
cd ninjaone-mcp
npm install
npm run build
```
### 选项 2 — 直接使用 `tsx` 运行（开发/测试）
```bash
git clone https://github.com/Allied-Business-Solutions/ninjaone-mcp.git
cd ninjaone-mcp
npm install
```
然后在下面的配置中使用 `npm run dev` 代替 `node dist/index.js`。
## 配置
### 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `NINJA_BASE_URL` | 是 | 忍者一体实例 URL（例如 `https://app.ninjarmm.com`） |
| `NINJA_CLIENT_ID` | 是 | 来自忍者一体开发者门户的 OAuth2 客户端 ID |
| `NINJA_CLIENT_SECRET` | 是 | 来自忍者一体开发者门户的 OAuth2 客户端密钥 |
通过复制示例创建 `.env` 文件：
```bash
cp .env.example .env
# 然后使用您的凭证编辑 .env
```
### 克劳德桌面
将以下内容添加到您的 `claude_desktop_config.json`：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"ninjaone": {
"command": "node",
"args": ["/absolute/path/to/ninjaone-mcp/dist/index.js"],
"env": {
"NINJA_BASE_URL": "https://app.ninjarmm.com",
"NINJA_CLIENT_ID": "your_client_id",
"NINJA_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
保存后重启克劳德桌面。
### 克劳德代码（CLI）
将服务器添加到您的项目或全局 MCP 配置：
```bash
claude mcp add ninjaone \
-e NINJA_BASE_URL=https://app.ninjarmm.com \
-e NINJA_CLIENT_ID=your_client_id \
-e NINJA_CLIENT_SECRET=your_client_secret \
-- node /absolute/path/to/ninjaone-mcp/dist/index.js
```
### 其他 MCP 客户端
服务器使用 **stdio 传输** 并遵循标准 MCP 协议。 将任何 MCP 兼容的客户端指向 `node dist/index.js` 并设置三个环境变量。
## 可用工具
### 设备（30 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_devices` | 列出所有受管设备，可选设备筛选 (`df`) 和分页 |
| `ninja_get_device` | 获取单个设备的完整详细信息 |
| `ninja_get_devices_detailed` | 列出具有详细设置和策略分配的设备 |
| `ninja_search_devices` | 按名称、主机名或序列号搜索设备 |
| `ninja_update_device` | 更新设备显示名称、位置、角色或策略 |
| `ninja_get_device_activities` | 获取设备的活动日志 |
| `ninja_get_device_alerts` | 获取设备上的活动警报 |
| `ninja_get_device_software` | 列出设备上安装的软件 |
| `ninja_get_device_os_patches` | 获取待处理/失败/已拒绝的 OS 补丁 |
| `ninja_get_device_installed_os_patches` | 获取 OS 补丁安装历史 |
| `ninja_get_device_software_patches` | 获取待处理/失败/已拒绝的软件补丁 |
| `ninja_get_device_installed_software_patches` | 获取软件补丁安装历史 |
| `ninja_get_device_volumes` | 获取磁盘卷信息（容量、可用空间、文件系统） |
| `ninja_get_device_disks` | 获取物理磁盘驱动器信息 |
| `ninja_get_device_network_interfaces` | 获取网络适配器、IP地址和 MAC 地址 |
| `ninja_get_device_processors` | 获取 CPU/处理器详细信息 |
| `ninja_get_device_windows_services` | 获取 Windows 服务状态 |
| `ninja_get_device_last_logged_on_user` | 获取最后登录的用户 |
| `ninja_get_device_active_jobs` | 获取设备上正在运行的作业 |
| `ninja_get_device_dashboard_url` | 获取设备在忍者一体仪表板中的直接 URL |
| `ninja_get_device_scripting_options` | 列出设备可用的脚本和操作 |
| `ninja_get_device_custom_fields` | 获取设备的自定义字段值 |
| `ninja_update_device_custom_fields` | 更新设备的自定义字段值 |
| `ninja_reboot_device` | 重启设备（正常或强制模式） |
| `ninja_run_script` | 在设备上运行自定义脚本或内置操作 |
| `ninja_submit_os_patch_scan` | 触发 OS 补丁扫描 |
| `ninja_submit_os_patch_apply` | 应用 OS 补丁 |
| `ninja_submit_software_patch_scan` | 触发软件补丁扫描 |
| `ninja_submit_software_patch_apply` | 应用软件补丁 |
| `ninja_approve_devices` | 批准或拒绝待处理的设备注册 |
### 组织（10 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_organizations` | 列出所有组织（客户），支持分页 |
| `ninja_get_organizations_detailed` | 列出具有完整设置和策略映射的组织 |
| `ninja_get_organization` | 获取特定组织的详细信息 |
| `ninja_create_organization` | 创建新的组织 |
| `ninja_update_organization` | 更新组织的名称、描述或批准模式 |
| `ninja_get_organization_devices` | 列出组织中的所有设备 |
| `ninja_get_organization_locations` | 列出组织的所有位置 |
| `ninja_create_organization_location` | 为组织创建新的位置 |
| `ninja_get_organization_custom_fields` | 获取组织的自定义字段值 |
| `ninja_get_organization_end_users` | 获取与组织关联的终端用户 |
### 警报（2 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_alerts` | 获取所有设备上的所有活动警报 |
| `ninja_reset_alert` | 取消/重置警报，UID 可选添加解决方案备注 |
### 活动（1 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_activities` | 查询具有类、日期范围、类型、用户和设备筛选的系统活动日志 |
### 工单（12 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_create_ticket` | 创建新的支持工单 |
| `ninja_get_ticket` | 获取工单 ID |
| `ninja_update_ticket` | 更新工单状态、指派人、严重程度、优先级或标签 |
| `ninja_add_ticket_comment` | 在工单中添加公共或私人评论 |
| `ninja_get_ticket_log` | 获取工单的变更日志 |
| `ninja_get_tickets_by_board` | 查询特定板块上的工单 |
| `ninja_list_boards` | 列出所有工单板块 |
| `ninja_list_ticket_statuses` | 列出所有可用的工单状态 |
| `ninja_list_ticket_forms` | 列出所有工单表单 |
| `ninja_get_ticket_form` | 获取特定工单表单的详细信息和字段 |
| `ninja_list_ticketing_users` | 列出工单中可用的应用用户和联系人 |
| `ninja_get_ticket_attributes` | 获取工单的自定义属性定义 |
### 查询/报告（19 种工具）
所有查询工具都支持 `df`（设备筛选）、`pageSize` 和 `cursor` 进行分页。
| 工具 | 描述 |
|------|-------------|
| `ninja_query_antivirus_status` | 整个设备上的 AV 产品状态 |
| `ninja_query_antivirus_threats` | 整个设备上检测到的 AV 威胁 |
| `ninja_query_device_health` | 设备健康报告（在线/离线、警报、补丁合规性） |
| `ninja_query_os_patches` | 整个设备上待处理/失败/已拒绝的 OS 补丁 |
| `ninja_query_software_patches` | 整个设备上待处理/失败/已拒绝的软件补丁 |
| `ninja_query_installed_os_patches` | 整个设备上的 OS 补丁安装历史 |
| `ninja_query_installed_software_patches` | 整个设备上的软件补丁安装历史 |
| `ninja_query_software` | 整个设备上的软件清单 |
| `ninja_query_logged_on_users` | 整个设备上的最后登录用户 |
| `ninja_query_computer_systems` | 整个设备上的硬件信息（制造商、型号、序列号） |
| `ninja_query_operating_systems` | 整个设备上的操作系统名称、版本和构建 |
| `ninja_query_network_interfaces` | 整个设备上的网络接口信息 |
| `ninja_query_disks` | 整个设备上的物理磁盘信息 |
| `ninja_query_volumes` | 整个设备上的磁盘卷信息 |
| `ninja_query_windows_services` | 整个设备上的 Windows 服务状态 |
| `ninja_query_custom_fields` | 整个设备上的自定义字段值 |
| `ninja_query_processors` | 整个设备上的 CPU 信息 |
| `ninja_query_backup_usage` | 整个设备上的备份存储使用情况 |
| `ninja_query_policy_overrides` | 整个设备上的策略覆盖 |
### 策略（4 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_policies` | 列出所有策略 |
| `ninja_get_device_policy_overrides` | 获取特定设备的策略覆盖 |
| `ninja_query_policy_overrides` | 查询所有设备上的策略覆盖 |
| `ninja_list_node_roles` | 列出所有可用的设备/节点角色 |
### 用户（7 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_users` | 列出所有用户（技术人员和终端用户） |
| `ninja_list_technicians` | 列出所有技术人员账户 |
| `ninja_get_technician` | 获取技术人员 ID |
| `ninja_list_end_users` | 列出所有终端用户 |
| `ninja_get_end_user` | 获取终端用户 ID |
| `ninja_list_user_roles` | 列出所有用户角色 |
| `ninja_list_contacts` | 列出所有联系人 |
### 备份（2 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_get_backup_jobs` | 获取备份作业历史和状态 |
| `ninja_get_integrity_check_jobs` | 获取备份完整性检查结果 |
### 系统（10 种工具）
| 工具 | 描述 |
|------|-------------|
| `ninja_list_groups` | 列出所有设备组 |
| `ninja_get_group_device_ids` | 获取特定组的设备 ID |
| `ninja_list_scheduled_tasks` | 列出所有计划的自动化任务 |
| `ninja_list_automation_scripts` | 列出所有自动化脚本 |
| `ninja_list_notification_channels` | 列出所有配置的通知渠道 |
| `ninja_list_custom_fields` | 列出所有自定义字段定义 |
| `ninja_list_locations` | 列出所有组织的所有位置 |
| `ninja_list_software_products` | 列出所有跟踪的软件产品 |
| `ninja_configure_webhook` | 为忍者一体事件配置 webhook 端点 |
| `ninja_disable_webhook` | 禁用配置的 webhook |
## 设备筛选语法
许多工具都接受 `df` 参数用于筛选设备。 示例：
```
org = 1 # ID 为 1 的组织中的设备
status = APPROVED # 仅限批准的设备
class in (WINDOWS_WORKSTATION, WINDOWS_SERVER)
location = 5 AND class = MAC
```
## 开发
```bash
# 以开发模式运行（无需构建步骤）
npm run dev
# 类型检查和编译
npm run build
# 启动编译后的服务器
npm start
```
## 项目结构
```
src/
index.ts # MCP 服务器入口点和请求路由
client.ts # 具有 OAuth2 令牌管理的忍者一体 HTTP 客户端
utils.ts # 共享实用程序
tools/
types.ts # ToolDef 接口
index.ts # 聚合所有工具数组
devices.ts # 设备管理工具
organizations.ts # 组织管理工具
alerts.ts # 警报工具
activities.ts # 活动日志工具
ticketing.ts # 工单工具
queries.ts # 整个 fleet 的查询/报告工具
policies.ts # 策略工具
users.ts # 用户管理工具
backup.ts # 备份工具
system.ts # 系统/管理员工具
```
## 许可证
MIT
