docs/netdata-ai/mcp/mcp-clients/claude-desktop.md
Configure Claude Desktop to access your Netdata infrastructure through MCP.
Claude Desktop launches MCP servers as child processes over stdio (the only transport the client supports today). Remote servers must be proxied through a launcher that exposes a stdio interface, such as nd-mcp or npx mcp-remote, before Claude Desktop can connect.
| Transport delivered to Claude Desktop | Support | Netdata Version | Notes |
|---|---|---|---|
| stdio (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Native Claude transport |
stdio (via npx mcp-remote) | ✅ Fully Supported | v2.7.2+ | Wraps Netdata HTTP/SSE in stdio |
| Direct HTTP / SSE | ⚠️ Use bridge | - | Requires a stdio bridge (Claude cannot speak HTTP/SSE directly) |
Reference: Claude Desktop’s official quickstart configures MPC servers by editing
claude_desktop_config.jsonand launching stdio bridges (https://modelcontextprotocol.io/docs/develop/connect-local-servers).
nd-mcp bridgenpx mcp-remote bridge for HTTP/SSE supportnd-mcp bridge - The stdio-to-websocket bridge for all Netdata versions. Find its absolute pathnpx mcp-remote@latest - Official MCP remote client supporting HTTP/SSE (requires Netdata v2.7.2+)export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
Download directly from claude.ai/download
Use the community AppImage project:
Claude Desktop supports MCP servers through two methods: Custom Connectors for remote servers (recommended), and traditional JSON configuration (manual).
Connect to your entire Netdata Cloud infrastructure through a single endpoint — no local Netdata setup or firewall changes needed.
Prerequisites:
scope:mcp
(create one)Edit claude_desktop_config.json (see Method 2 below for file location):
{
"mcpServers": {
"netdata-cloud": {
"command": "npx",
"args": [
"mcp-remote@latest",
"https://app.netdata.cloud/api/v1/mcp",
"--header",
"Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
]
}
}
}
Replace YOUR_NETDATA_CLOUD_API_TOKEN with your
Netdata Cloud API token (must have scope:mcp).
Restart Claude Desktop after saving.
For more details, see
Netdata Cloud MCP.
The following methods connect directly to a Netdata Agent or Parent on your network.
Anthropic’s custom connectors beta lets Team/Enterprise owners add remote servers through Claude’s UI. The connector flow relies on the server’s OAuth or custom auth and does not expose arbitrary HTTP headers. Follow the server developer’s instructions to complete the OAuth hand-off; the UI handles credential storage (https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
Because Netdata currently authenticates via bearer tokens, you’ll need the stdio launcher methods below unless you front your Netdata MCP endpoint with an OAuth-capable bridge.
For all Netdata versions (v2.6.0+), you can manually configure MCP servers:
Ctrl+,)Cmd+,)claude_desktop_config.json in your system’s config folder:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/claude/claude_desktop_config.jsonAdd the Netdata configuration:
{
"mcpServers": {
"netdata": {
"command": "/usr/sbin/nd-mcp",
"args": [
"ws://YOUR_NETDATA_IP:19999/mcp"
]
}
}
}
npx mcp-remote (v2.7.2+)For Netdata v2.7.2+ with HTTP/SSE support. mcp-remote wraps remote transports in a stdio session Claude can launch (https://modelcontextprotocol.io/docs/develop/connect-local-servers). Edit claude_desktop_config.json as above.
{
"mcpServers": {
"netdata": {
"command": "npx",
"args": [
"mcp-remote@latest",
"--http",
"http://YOUR_NETDATA_IP:19999/mcp",
"--allow-http",
"--header",
"Authorization: Bearer NETDATA_MCP_API_KEY"
]
}
}
}
For SSE transport instead of HTTP:
{
"mcpServers": {
"netdata": {
"command": "npx",
"args": [
"mcp-remote@latest",
"--sse",
"http://YOUR_NETDATA_IP:19999/mcp",
"--allow-http",
"--header",
"Authorization: Bearer NETDATA_MCP_API_KEY"
]
}
}
}
Replace in all examples:
/usr/sbin/nd-mcp - With your actual nd-mcp path (nd-mcp method only)YOUR_NETDATA_IP - IP address or hostname of your Netdata Agent/ParentNETDATA_MCP_API_KEY - Your Netdata MCP API keyND_MCP_BEARER_TOKEN - Export this environment variable with your API key before launching Claude Desktop (nd-mcp method only)Simply ask Claude about your infrastructure:
What's the current CPU usage across all my servers?
Show me any anomalies in the last 4 hours
Which processes are consuming the most memory?
Are there any critical alerts active?
Search the logs for authentication failures
Claude Desktop supports multiple environments:
Add multiple connectors for different environments via Settings → Connectors:
Netdata Production pointing to http://prod-parent:19999/mcpNetdata Staging pointing to http://stage-parent:19999/mcpFor local bridges, add multiple configurations in claude_desktop_config.json and enable/disable as needed:
{
"mcpServers": {
"netdata-production": {
"command": "/usr/sbin/nd-mcp",
"args": ["ws://prod-parent:19999/mcp"]
},
"netdata-staging": {
"command": "/usr/sbin/nd-mcp",
"args": ["ws://stage-parent:19999/mcp"]
}
}
}
Use the toggle switch in settings to enable only one at a time.
ℹ️ Set
ND_MCP_BEARER_TOKENto the appropriate key before switching between environments to avoid storing secrets in the configuration file.
Connect to your main Netdata Parent that has visibility across all environments.
curl http://YOUR_NETDATA_IP:19999/api/v3/info.exe extension