Netdata

Netdata MCP

模型上下文协议（MCP） 与 Netdata 的交互有两个方向：

• Netdata 作为 MCP 服务——AI 助手和客户端（Claude、Cursor、VS Code、CLI 等）连接到 Netdata，以查询你的基础设施。本页面介绍服务端设置；各客户端的说明请参阅受支持的 AI 客户端。
• Netdata 作为 MCP 客户端——Netdata Cloud 连接到你自己的 MCP 服务（GitHub、PagerDuty、Atlassian 或任何自定义 HTTPS MCP 服务），让 Netdata AI 在故障排查时获取团队的组织知识。请参阅 MCP Connections。

本页面其余内容介绍 Netdata 作为 MCP 服务。

Netdata 提供 MCP 服务，让 AI 助手能够与基础设施监控数据交互。你可以通过以下方式连接：

• Netdata Cloud——一个由云端托管的统一端点 https://app.netdata.cloud/api/v1/mcp，可全面查看所有节点。无需桥接，无需更改防火墙。
• 本地 Agent 或父节点 — 直接连接到网络中的任意 Netdata Agent 或父节点 （v2.6.0+），地址为 http://YOUR_IP:19999/mcp。

这两种方式都可通过 MCP 全面访问所有 可用的可观测性数据：

• 节点发现 - 硬件规格、操作系统详细信息、版本信息、流式传输拓扑以及关联的元数据
• 指标发现 - 可对上下文、实例、维度和标签进行全文搜索
• 功能发现 - 访问系统功能，包括 processes、network-connections、streaming、systemd-journal、windows-events 等
• 告警发现 - 实时查看活动告警和已触发告警
• 指标查询 - 复杂的聚合和分组，并支持 ML 驱动的异常检测
• 指标评分 - 利用异常检测和指标关联进行根因分析
• 告警历史记录 - 完整的告警状态转换日志和状态变更
• 功能执行 - 在任意已连接节点上执行 Netdata 功能（需要 Netdata 父节点）
• 日志探索 - 访问任意已连接节点的日志（需要 Netdata 父节点）

AI 助手可见的数据取决于其连接位置：

连接	可见范围
Netdata Cloud	整个基础设施中的所有节点
Netdata 父节点	连接到该父节点的所有子节点
Netdata 子节点/独立节点	仅该特定节点

功能	Cloud MCP	Agent/Parent MCP
范围	所有节点	单个 Agent/父节点
端点	app.netdata.cloud/api/v1/mcp	YOUR_IP:19999/mcp
传输方式	Streamable HTTP	HTTP、SSE、WebSocket
身份验证	Cloud API 令牌（scope:mcp）	本地 MCP API 密钥（启用 bearer 保护时为必需）
网络访问	仅限互联网	必须直接访问 Netdata IP
本地设置	无	某些客户端可能需要桥接

Netdata Cloud MCP

通过单个 MCP 端点将 AI 助手连接到整个 Netdata Cloud 基础设施 — 无需本地设置、桥接或更改防火墙。

前提条件

1. Netdata Cloud 账户，并使用付费计划
2. 具有 scope:mcp 的 API 令牌 — 在 API Tokens 设置中创建
3. 已认领到 Netdata Cloud 的节点 — Cloud MCP 服务只能访问 已连接到 Netdata Cloud 空间的节点

端点

https://app.netdata.cloud/api/v1/mcp

传输方式： Streamable HTTP（无状态，可在负载均衡器和 CDN 后使用）

身份验证

所有发往 Cloud MCP 端点的请求都必须在 Authorization 标头中包含 Bearer 令牌：

Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN

创建 API 令牌

1. 登录 Netdata Cloud
2. 点击左下角的个人资料图片
3. 选择 用户设置
4. 前往 API 令牌 部分
5. 创建一个带有 scope:mcp 的新令牌
6. 复制并妥善保存令牌——你将无法再次查看

更多详情请参阅 API 令牌。

连接配置

Claude Code（单行设置）

如果你使用 Claude Code，只需一条命令，即可在任何会话中注册 Netdata Cloud MCP 服务——无需编辑 JSON：

claude mcp add --transport http --scope user netdata-cloud \
  https://app.netdata.cloud/api/v1/mcp \
  --header "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"

将 YOUR_NETDATA_CLOUD_API_TOKEN 替换为带有 scope:mcp 的令牌——请参阅上方的创建 API 令牌，或直接前往 Netdata Cloud 中的 用户设置 → API 令牌。

作用范围标志：

• --scope user — 在此计算机上的所有项目中均可使用（个人使用推荐）
• --scope local — 仅用于此项目，仅你可用（省略 --scope 时的默认值）
• --scope project — 用于此项目，提交到 .mcp.json 并与团队共享（请勿使用原始令牌；改为引用环境变量）

实用的配套命令：

claude mcp list                          # show all configured servers and their connection status
claude mcp get netdata-cloud             # show the configuration for this server
claude mcp remove netdata-cloud -s user  # remove the server (match the scope you added with)

添加服务后，重启 Claude Code 会话，以便加载新工具。

如需了解更多 Claude Code 选项——包括连接到本地 Netdata Agent 或 Parent——请参阅 Claude Code 指南。

通用 MCP 客户端（HTTP 传输）

对于支持 Streamable HTTP 传输的任何 MCP 客户端：

{
  "mcpServers": {
    "netdata-cloud": {
      "type": "http",
      "url": "https://app.netdata.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
      }
    }
  }
}

需要 stdio 桥接的客户端

对于仅支持 stdio 传输的 MCP 客户端，请使用 npx mcp-remote 作为桥接：

{
  "mcpServers": {
    "netdata-cloud": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://app.netdata.cloud/api/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
      ]
    }
  }
}

将 YOUR_NETDATA_CLOUD_API_TOKEN 替换为你的 API 令牌 （必须带有 scope:mcp）。

Cloud MCP 故障排查

身份验证错误

• 确认 API 令牌带有 scope:mcp
• 确保令牌通过 Authorization: Bearer <token> 传递（而不是作为查询参数）
• 确认你的 Netdata Cloud 订阅 包含一个采用付费计划的空间

看不到节点

• 确认你的节点已认领到 Netdata Cloud，并显示在 Web 仪表板中
• 检查 Agent 是否在线并向 Cloud 传输数据

连接问题

• 端点使用 HTTPS——无需 --allow-http 标志
• 测试连接：curl -H "Authorization: Bearer YOUR_TOKEN" https://app.netdata.cloud/api/v1/mcp

本地 Agent 或 Parent MCP

直接连接到网络中的任意 Netdata Agent 或 Parent。所有 Netdata Agent 和 Parent（v2.6.0+）都内置 MCP 服务，地址为 http://YOUR_IP:19999/mcp。

Netdata 会在启动时自动生成本地 MCP API 密钥。身份验证行为取决于 [web].bearer token protection：

• Bearer 保护已禁用（no）：匿名 MCP 访问可用于非敏感操作（指标、告警、节点信息）。API 密钥可解锁敏感操作。
• Bearer 保护已启用（yes）：所有 MCP 传输方式（HTTP、SSE、WebSocket）都拒绝匿名 MCP 访问。所有 MCP 请求都必须使用 API 密钥。
• 需要认领：只有在 Agent 已认领到 Netdata Cloud 时，Agent 才接受 API 密钥。未认领的 Agent 会拒绝所有密钥，因此启用 Bearer 保护时，MCP 不可用。
• 仅限 MCP：API 密钥不能授权访问 Agent 的 REST API（/api/...）。启用 Bearer 保护后，这些端点仍需要 Cloud 签发的 Bearer 令牌。

传输选项

Netdata 通过多种传输选项实现 MCP 协议：

传输方式	端点	使用场景	版本要求
WebSocket	ws://YOUR_IP:19999/mcp	原始传输方式，需要 nd-mcp 桥接器供 stdio 客户端使用	v2.6.0+
HTTP Streamable	http://YOUR_IP:19999/mcp	支持 HTTP 的 AI 客户端可直接连接	v2.7.2+
SSE	http://YOUR_IP:19999/sse	用于实时流式传输的服务器发送事件	v2.7.2+

• 直接连接（v2.7.2+）：支持 HTTP 或 SSE 传输的 AI 客户端可以直接连接 Netdata
• 需要桥接器：仅支持 stdio 的 AI 客户端需要使用 nd-mcp（stdio-to-websocket）或 mcp-remote（stdio-to-http 或 stdio-to-sse）桥接器
• 推荐的身份验证方式：通过 Authorization: Bearer <mcp_key> 传递 MCP API 密钥。
• 向后兼容性：WebSocket 也接受 ?api_key=<mcp_key>。仅将此方式用于旧版客户端，因为代理和工具更可能记录 URL 查询字符串。
• 请求限制：HTTP 或 SSE 请求正文大小约为 1 MiB，WebSocket 消息最大为 1 MiB（超出时会以代码 1009 关闭连接）。JSON-RPC 批次最多可包含 64 个请求。响应总大小达到 16 MiB 后，剩余请求将不再执行：每个带有 id 的有效请求都会收到 -32001 错误，任何会导致超出限制的响应也会被替换为该错误。

在 netdata.conf 中进行 MCP 访问控制

使用专用的 MCP ACL，独立于仪表板和流式传输控制网络级别的 MCP 访问：

[web]
    allow connections from = 10.* 192.168.* localhost
    allow dashboard from = 10.* 192.168.* localhost
    allow mcp from = 10.* 192.168.* localhost
    allow streaming from = *
    allow mcp by dns = heuristic

• allow mcp from 控制对 /mcp、/sse 和 MCP WebSocket 协议的访问。
• allow connections from 仍是所有功能的全局第一道关卡。
• 对于面向互联网的 Parent，请将 allow mcp from 限制为可信网络。

官方 MCP 远程客户端（mcp-remote）

如果你的 AI 客户端不直接支持 HTTP/SSE，且你不想使用 nd-mcp，可以使用官方 MCP 远程客户端（需要 Netdata v2.7.2+）：

# Export your MCP key once per shell
export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"

# For HTTP transport
npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer $NETDATA_MCP_API_KEY"

# For SSE transport
npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer $NETDATA_MCP_API_KEY"

**注意：**非 HTTPS 连接必须使用 --allow-http 标志。由于流量不会加密，请仅在可信网络上使用。

查找 nd-mcp 桥接器

注意：借助新增的 HTTP 和 SSE 传输方式，许多 AI 客户端现在可以直接连接 Netdata，无需 nd-mcp。请查阅 AI 客户端的文档，确认是否支持直接通过 HTTP 或 SSE 连接。

只有以下 AI 客户端才需要 nd-mcp 桥接器：

• 仅支持 stdio 通信的客户端（例如某些桌面应用）
• 无法直接使用 HTTP 或 SSE 传输方式的客户端
• 无法使用 npx mcp-remote@latest 的客户端

nd-mcp 桥接器需要在运行 AI 客户端的桌面电脑或笔记本电脑上可用。由于大多数用户会在远程服务而非本地机器上运行 Netdata，因此有两种选择：

1. 如果本地已安装 Netdata - 使用现有的 nd-mcp
2. 如果 Netdata 仅安装在远程服务上 - 在桌面电脑或笔记本电脑上构建 nd-mcp

选项 1：使用现有 nd-mcp

如果桌面电脑或笔记本电脑上已安装 Netdata，请查找现有桥接器：

Linux

# Try these locations in order:
which nd-mcp
ls -la /usr/sbin/nd-mcp
ls -la /usr/bin/nd-mcp
ls -la /opt/netdata/usr/bin/nd-mcp
ls -la /usr/local/bin/nd-mcp
ls -la /usr/local/netdata/usr/bin/nd-mcp

# Or search for it:
find / -name "nd-mcp" 2>/dev/null

常见位置：

• 原生软件包（apt、yum 等）：/usr/sbin/nd-mcp 或 /usr/bin/nd-mcp
• 静态安装：/opt/netdata/usr/bin/nd-mcp
• 从源代码构建：/usr/local/netdata/usr/bin/nd-mcp

macOS

# Try these locations:
which nd-mcp
ls -la /usr/local/bin/nd-mcp
ls -la /usr/local/netdata/usr/bin/nd-mcp
ls -la /opt/homebrew/bin/nd-mcp

# Or search for it:
find / -name "nd-mcp" 2>/dev/null

Windows

# Check common locations:
dir "C:\Program Files\Netdata\usr\bin\nd-mcp.exe"
dir "C:\Netdata\usr\bin\nd-mcp.exe"
# Or search for it:
where nd-mcp.exe

选项 2：为桌面应用构建 nd-mcp

如果本地未安装 Netdata，可以只构建 nd-mcp 桥接程序。Netdata 提供了三种实现方式，请选择最适合你环境的一种：

1. Go 桥接程序（推荐）- Go 桥接程序源代码

   • 生成无需依赖的单个二进制文件
   • 创建名为 nd-mcp 的可执行文件（Windows 上为 nd-mcp.exe）
   • 包含 build.sh 和 build.bat（适用于 Windows）

2. Node.js 桥接程序 - Node.js 桥接程序源代码

   • 适合已安装 Node.js 的情况
   • 创建名为 nd-mcp.js 的脚本
   • 包含 build.sh

3. Python 桥接程序 - Python 桥接程序源代码

   • 适合已安装 Python 的情况
   • 创建名为 nd-mcp.py 的脚本
   • 包含 build.sh

构建方法：

# Clone the Netdata repository
git clone https://github.com/netdata/netdata.git
cd netdata

# Choose your preferred implementation
cd src/web/mcp/bridges/stdio-golang/  # or stdio-nodejs/ or stdio-python/

# Build the bridge
./build.sh  # On Windows with the Go version, use build.bat

# The executable will be created with different names:
# - Go: nd-mcp
# - Node.js: nd-mcp.js
# - Python: nd-mcp.py

# Test the bridge with your Netdata instance (replace localhost with your Netdata IP)
./nd-mcp ws://localhost:19999/mcp      # Go bridge
./nd-mcp.js ws://localhost:19999/mcp   # Node.js bridge  
./nd-mcp.py ws://localhost:19999/mcp   # Python bridge

# You should see:
# nd-mcp: Connecting to ws://localhost:19999/mcp...
# nd-mcp: Connected
# Press Ctrl+C to stop the test

# Get the absolute path for your AI client configuration
pwd  # Shows current directory
# Example output: /home/user/netdata/src/web/mcp/bridges/stdio-golang
# Your nd-mcp path would be: /home/user/netdata/src/web/mcp/bridges/stdio-golang/nd-mcp

重要： 配置 AI 客户端时，请使用可执行文件的完整绝对路径：

• Go 桥接程序：/path/to/bridges/stdio-golang/nd-mcp
• Node.js 桥接程序：/path/to/bridges/stdio-nodejs/nd-mcp.js
• Python 桥接程序：/path/to/bridges/stdio-python/nd-mcp.py

验证桥接程序是否正常工作

获取 nd-mcp（无论是来自现有安装还是自行构建）后，请进行测试：

# Test connection to your Netdata instance (replace YOUR_NETDATA_IP with actual IP)
/path/to/nd-mcp ws://YOUR_NETDATA_IP:19999/mcp

# You should see:
# nd-mcp: Connecting to ws://YOUR_NETDATA_IP:19999/mcp...
# nd-mcp: Connected
# Press Ctrl+C to stop the test

使用 MCP 远程客户端

官方 MCP 远程客户端（mcp-remote）是另一种桥接程序，可让仅支持 stdio 的 AI 客户端连接到 Netdata 的 HTTP 和 SSE 传输（需要 Netdata v2.7.2+）。与仅支持 WebSocket 的 nd-mcp 不同，mcp-remote 提供了更广泛的传输兼容性。

何时使用 MCP Remote

以下情况可使用 mcp-remote：

• 你的 AI 客户端仅支持 stdio 通信
• 你想使用 HTTP 或 SSE 传输，而不是 WebSocket
• 你运行的是 Netdata v2.7.2 或更高版本
• 你不想构建或安装 nd-mcp

安装

无需安装，mcp-remote 可通过 npx 运行：

# Test the connection
npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer YOUR_API_KEY"

传输选项

mcp-remote 支持多种传输策略：

# HTTP transport (recommended)
npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer YOUR_API_KEY"

# SSE transport
npx mcp-remote@latest --sse http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer YOUR_API_KEY"

# Auto-detect with fallback (tries SSE first, falls back to HTTP)
npx mcp-remote@latest --transport sse-first http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer YOUR_API_KEY"

# HTTPS (no --allow-http flag needed)
npx mcp-remote@latest --http https://YOUR_NETDATA_IP:19999/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

常用选项

选项	说明	示例
--http	使用 HTTP 传输	--http http://host:19999/mcp
--sse	使用 SSE 传输	--sse http://host:19999/mcp
--allow-http	允许非 HTTPS 连接（HTTP URL 必需）	--allow-http
--header	添加自定义标头（用于身份验证）	--header "Authorization: Bearer KEY"
--transport	传输策略	--transport sse-first（先尝试 SSE，失败时回退到 HTTP）
--debug	启用调试日志	--debug
--host	OAuth 回调主机（默认：localhost）	--host 127.0.0.1
端口号	OAuth 回调端口（可选）	9696

身份验证

对于 Netdata MCP，请通过 Authorization 标头传递 API 密钥：

# Using environment variable (recommended)
export NETDATA_MCP_API_KEY="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"

npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer $NETDATA_MCP_API_KEY"

安全提示： 非 HTTPS 连接需要使用 --allow-http 标志。仅在可信网络中使用此选项，因为流量不会加密。

故障排除

连接问题：

# Enable debug logging
npx mcp-remote@latest --debug --http http://YOUR_NETDATA_IP:19999/mcp \
  --allow-http \
  --header "Authorization: Bearer YOUR_API_KEY"

# Check debug logs (stored in ~/.mcp-auth/)
cat ~/.mcp-auth/*_debug.log

清除身份验证状态：

# Remove cached credentials
rm -rf ~/.mcp-auth

参数中包含空格：

某些 AI 客户端（Cursor、Windows 上的 Claude Desktop）处理带空格的参数时会遇到问题。可使用环境变量作为替代方案：

{
  "mcpServers": {
    "netdata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "--http",
        "http://YOUR_IP:19999/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

版本管理

始终使用最新版本：

# Force npx to check for latest version
npx mcp-remote@latest --http http://YOUR_NETDATA_IP:19999/mcp

也可以在 AI 客户端配置中使用：

{
  "args": ["mcp-remote@latest", "--http", "..."]
}

更多详情，请参阅 mcp-remote 官方文档。

查找 API 密钥

启用 bearer 保护时，需要 MCP API 密钥。禁用 bearer 保护时，日志和实时系统信息等敏感功能仍需要该密钥。Netdata 会在启动时自动生成 API 密钥。该密钥存储在你要连接的 Netdata 服务上的文件中。

你需要获取将要连接的 Netdata 的 API 密钥（通常是 Netdata Parent）。

注意：此临时 API 密钥机制最终将由与 Netdata Cloud 的集成取代。

查找 API 密钥文件

# Try the default location first:
sudo cat /var/lib/netdata/mcp_dev_preview_api_key

# For static installations:
sudo cat /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key

# If not found, search for it:
sudo find / -name "mcp_dev_preview_api_key" 2>/dev/null

复制 API 密钥

文件中包含一个 UUID，格式如下：

a1b2c3d4-e5f6-7890-abcd-ef1234567890

复制整个字符串，稍后需要将其用于 AI 客户端配置。

找不到 API 密钥文件？

如果文件不存在：

1. 确保使用的是较新版本的 Netdata
2. 重启 Netdata：sudo systemctl restart netdata
3. 重启后再次检查文件

AI 客户端配置

AI 客户端可根据其传输方式支持情况，通过不同方式连接到 Netdata MCP：

直接连接（HTTP/SSE）

适用于支持 HTTP 或 SSE 传输方式的 AI 客户端：

{
  "mcpServers": {
    "netdata": {
      "type": "http",
      "url": "http://IP_OF_YOUR_NETDATA:19999/mcp",
      "headers": [
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

或使用 SSE：

{
  "mcpServers": {
    "netdata": {
      "type": "sse",
      "url": "http://IP_OF_YOUR_NETDATA:19999/mcp?transport=sse",
      "headers": [
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

使用 nd-mcp 桥接程序（stdio）

适用于仅支持 stdio 的 AI 客户端：

{
  "mcpServers": {
    "netdata": {
      "command": "/usr/sbin/nd-mcp",
      "args": [
        "--bearer",
        "YOUR_API_KEY",
        "ws://IP_OF_YOUR_NETDATA:19999/mcp"
      ]
    }
  }
}

使用官方 MCP 远程客户端

{
  "mcpServers": {
    "netdata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "--http",
        "http://IP_OF_YOUR_NETDATA:19999/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

替换：

• IP_OF_YOUR_NETDATA：Netdata 实例的 IP/主机名
• YOUR_API_KEY：上述文件中的 API 密钥
• /usr/sbin/nd-mcp：替换为实际的 nd-mcp 路径（如果使用桥接程序）

多个 MCP 服务

你可以配置多个 Netdata 实例：

{
  "mcpServers": {
    "netdata-production": {
      "command": "/usr/sbin/nd-mcp",
      "args": ["--bearer", "PROD_KEY", "ws://prod-parent:19999/mcp"]
    },
    "netdata-testing": {
      "command": "/usr/sbin/nd-mcp",
      "args": ["--bearer", "TEST_KEY", "ws://test-parent:19999/mcp"]
    }
  }
}

旧版查询字符串支持

为兼容较旧的工具，Netdata 仍会在 /mcp 端点接受 ?api_key=YOUR_API_KEY 查询参数。新的集成应优先使用 Authorization: Bearer YOUR_API_KEY 标头，但如果你要逐步迁移，仍可使用查询字符串形式。

AI 客户端专项文档

有关特定 AI 客户端的详细配置说明，请参阅：

聊天客户端：

• Claude Desktop - Anthropic 的桌面 AI 助手
• Cursor - AI 驱动的代码编辑器
• Visual Studio Code - 支持 MCP 的 VS Code
• JetBrains IDEs - IntelliJ、PyCharm、WebStorm 等

DevOps 副驾驶：

• Claude Code - Anthropic 的 Claude 命令行工具
• Gemini CLI - Google 的 Gemini CLI
• OpenAI Codex CLI - OpenAI 的 Codex CLI
• Crush - Charmbracelet 的炫酷终端 AI
• OpenCode - SST 的终端 AI 助手

每份指南都包含针对相应客户端优化的传输方式支持矩阵和配置示例。