| 1 | # Claude Desktop |
| 2 | |
| 3 | Configure Claude Desktop to access your Netdata infrastructure through MCP. |
| 4 | |
| 5 | ## Transport Support |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | | Transport delivered to Claude Desktop | Support | Netdata Version | Notes | |
| 10 | |--------------------------------------|---------|-----------------|-------| |
| 11 | | **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Native Claude transport | |
| 12 | | **stdio** (via `npx mcp-remote`) | ✅ Fully Supported | v2.7.2+ | Wraps Netdata HTTP/SSE in stdio | |
| 13 | | **Direct HTTP / SSE** | ⚠️ Use bridge | - | Requires a stdio bridge (Claude cannot speak HTTP/SSE directly) | |
| 14 | |
| 15 | > **Reference:** Claude Desktop’s official quickstart configures MPC servers by editing `claude_desktop_config.json` and launching stdio bridges (https://modelcontextprotocol.io/docs/develop/connect-local-servers). |
| 16 | |
| 17 | ## Prerequisites |
| 18 | |
| 19 | 1. **Claude Desktop installed** - Download from [claude.ai/download](https://claude.ai/download) |
| 20 | 2. **Netdata v2.6.0 or later** with MCP support - Prefer a Netdata Parent to get infrastructure level visibility. Your AI Client (running on your desktop or laptop) needs to have direct network access to the Netdata IP and port (usually 19999). |
| 21 | - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge |
| 22 | - **v2.7.2+**: Can use `npx mcp-remote` bridge for HTTP/SSE support |
| 23 | 3. **Bridge required: Choose one:** |
| 24 | - `nd-mcp` bridge - The stdio-to-websocket bridge for all Netdata versions. [Find its absolute path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge) |
| 25 | - `npx mcp-remote@latest` - Official MCP remote client supporting HTTP/SSE (requires Netdata v2.7.2+) |
| 26 | 4. **Netdata MCP API key loaded into the environment** (recommended) - export it before launching Claude Desktop to avoid exposing it in config files: |
| 27 | ```bash |
| 28 | export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)" |
| 29 | ``` |
| 30 | Each Netdata Agent or Parent has its own unique API key for MCP - [Find your Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key) |
| 31 | |
| 32 | ## Platform-Specific Installation |
| 33 | |
| 34 | ### Windows & macOS |
| 35 | |
| 36 | Download directly from [claude.ai/download](https://claude.ai/download) |
| 37 | |
| 38 | ### Linux |
| 39 | |
| 40 | Use the community AppImage project: |
| 41 | |
| 42 | 1. Download from [github.com/fsoft72/claude-desktop-to-appimage](https://github.com/fsoft72/claude-desktop-to-appimage) |
| 43 | 2. For best experience, install [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) |
| 44 | |
| 45 | ## Configuration Methods |
| 46 | |
| 47 | Claude Desktop supports MCP servers through two methods: Custom Connectors for remote servers (recommended), and traditional JSON configuration (manual). |
| 48 | |
| 49 | ### Netdata Cloud MCP |
| 50 | |
| 51 | Connect to your entire Netdata Cloud infrastructure |
| 52 | through a single endpoint — no local Netdata setup |
| 53 | or firewall changes needed. |
| 54 | |
| 55 | **Prerequisites:** |
| 56 | |
| 57 | - Netdata Cloud account with a Paid plan |
| 58 | - Nodes claimed to Netdata Cloud |
| 59 | - API token with `scope:mcp` |
| 60 | ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md)) |
| 61 | |
| 62 | Edit `claude_desktop_config.json` (see Method 2 below for file location): |
| 63 | |
| 64 | ```json |
| 65 | { |
| 66 | "mcpServers": { |
| 67 | "netdata-cloud": { |
| 68 | "command": "npx", |
| 69 | "args": [ |
| 70 | "mcp-remote@latest", |
| 71 | "https://app.netdata.cloud/api/v1/mcp", |
| 72 | "--header", |
| 73 | "Authorization: Bearer YOUR_NETDATA_CLOUD_API_TOKEN" |
| 74 | ] |
| 75 | } |
| 76 | } |
| 77 | } |
| 78 | ``` |
| 79 | |
| 80 | Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your |
| 81 | Netdata Cloud API token (must have `scope:mcp`). |
| 82 | Restart Claude Desktop after saving. |
| 83 | For more details, see |
| 84 | [Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp). |
| 85 | |
| 86 | ### Local Agent or Parent |
| 87 | |
| 88 | The following methods connect directly to a Netdata Agent or Parent on your network. |
| 89 | |
| 90 | #### Method 1: Claude Desktop Custom Connectors (Anthropic-hosted beta) |
| 91 | |
| 92 | 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). |
| 93 | |
| 94 | 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. |
| 95 | |
| 96 | #### Method 2: Traditional JSON Configuration with nd-mcp Bridge |
| 97 | |
| 98 | For all Netdata versions (v2.6.0+), you can manually configure MCP servers: |
| 99 | |
| 100 | 1. Open Claude Desktop |
| 101 | 2. Navigate to Settings: |
| 102 | - **Windows/Linux**: File → Settings → Developer (or `Ctrl+,`) |
| 103 | - **macOS**: Claude → Settings → Developer (or `Cmd+,`) |
| 104 | 3. Click "Edit Config" button |
| 105 | 4. This opens `claude_desktop_config.json` in your system’s config folder: |
| 106 | - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| 107 | - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` |
| 108 | - **Linux** (preview builds): `~/.config/claude/claude_desktop_config.json` |
| 109 | |
| 110 | Add the Netdata configuration: |
| 111 | |
| 112 | ```json |
| 113 | { |
| 114 | "mcpServers": { |
| 115 | "netdata": { |
| 116 | "command": "/usr/sbin/nd-mcp", |
| 117 | "args": [ |
| 118 | "ws://YOUR_NETDATA_IP:19999/mcp" |
| 119 | ] |
| 120 | } |
| 121 | } |
| 122 | } |
| 123 | ``` |
| 124 | |
| 125 | 5. Save the configuration file |
| 126 | 6. **Restart Claude Desktop** (required for changes to take effect) |
| 127 | |
| 128 | #### Method 3: Traditional JSON Configuration with `npx mcp-remote` (v2.7.2+) |
| 129 | |
| 130 | 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. |
| 131 | |
| 132 | ```json |
| 133 | { |
| 134 | "mcpServers": { |
| 135 | "netdata": { |
| 136 | "command": "npx", |
| 137 | "args": [ |
| 138 | "mcp-remote@latest", |
| 139 | "--http", |
| 140 | "http://YOUR_NETDATA_IP:19999/mcp", |
| 141 | "--allow-http", |
| 142 | "--header", |
| 143 | "Authorization: Bearer NETDATA_MCP_API_KEY" |
| 144 | ] |
| 145 | } |
| 146 | } |
| 147 | } |
| 148 | ``` |
| 149 | |
| 150 | For SSE transport instead of HTTP: |
| 151 | |
| 152 | ```json |
| 153 | { |
| 154 | "mcpServers": { |
| 155 | "netdata": { |
| 156 | "command": "npx", |
| 157 | "args": [ |
| 158 | "mcp-remote@latest", |
| 159 | "--sse", |
| 160 | "http://YOUR_NETDATA_IP:19999/mcp", |
| 161 | "--allow-http", |
| 162 | "--header", |
| 163 | "Authorization: Bearer NETDATA_MCP_API_KEY" |
| 164 | ] |
| 165 | } |
| 166 | } |
| 167 | } |
| 168 | ``` |
| 169 | |
| 170 | Replace in all examples: |
| 171 | |
| 172 | - `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge) (nd-mcp method only) |
| 173 | - `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent |
| 174 | - `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key) |
| 175 | - `ND_MCP_BEARER_TOKEN` - Export this environment variable with your API key before launching Claude Desktop (nd-mcp method only) |
| 176 | |
| 177 | ## Verify Connection |
| 178 | |
| 179 | 1. Click the "Search and tools" button (below the prompt) |
| 180 | 2. You should see "netdata" listed among available tools |
| 181 | 3. If not visible, check your configuration and restart |
| 182 | |
| 183 | ## Usage Examples |
| 184 | |
| 185 | Simply ask Claude about your infrastructure: |
| 186 | |
| 187 | ``` |
| 188 | What's the current CPU usage across all my servers? |
| 189 | Show me any anomalies in the last 4 hours |
| 190 | Which processes are consuming the most memory? |
| 191 | Are there any critical alerts active? |
| 192 | Search the logs for authentication failures |
| 193 | ``` |
| 194 | |
| 195 | ## Multiple Environments |
| 196 | |
| 197 | Claude Desktop supports multiple environments: |
| 198 | |
| 199 | ### Option 1: Multiple Custom Connectors (Recommended) |
| 200 | |
| 201 | Add multiple connectors for different environments via **Settings → Connectors**: |
| 202 | |
| 203 | - Add `Netdata Production` pointing to `http://prod-parent:19999/mcp` |
| 204 | - Add `Netdata Staging` pointing to `http://stage-parent:19999/mcp` |
| 205 | - Enable/disable connectors as needed |
| 206 | |
| 207 | ### Option 2: Toggle JSON Configuration |
| 208 | |
| 209 | For local bridges, add multiple configurations in `claude_desktop_config.json` and enable/disable as needed: |
| 210 | |
| 211 | ```json |
| 212 | { |
| 213 | "mcpServers": { |
| 214 | "netdata-production": { |
| 215 | "command": "/usr/sbin/nd-mcp", |
| 216 | "args": ["ws://prod-parent:19999/mcp"] |
| 217 | }, |
| 218 | "netdata-staging": { |
| 219 | "command": "/usr/sbin/nd-mcp", |
| 220 | "args": ["ws://stage-parent:19999/mcp"] |
| 221 | } |
| 222 | } |
| 223 | } |
| 224 | ``` |
| 225 | |
| 226 | Use the toggle switch in settings to enable only one at a time. |
| 227 | |
| 228 | > ℹ️ Set `ND_MCP_BEARER_TOKEN` to the appropriate key before switching between environments to avoid storing secrets in the configuration file. |
| 229 | |
| 230 | ### Option 3: Single Parent |
| 231 | |
| 232 | Connect to your main Netdata Parent that has visibility across all environments. |
| 233 | |
| 234 | ## Troubleshooting |
| 235 | |
| 236 | ### Netdata Not Appearing in Tools |
| 237 | |
| 238 | - Ensure configuration file is valid JSON |
| 239 | - Restart Claude Desktop after configuration changes |
| 240 | - Check the bridge path exists and is executable |
| 241 | |
| 242 | ### Connection Errors |
| 243 | |
| 244 | - Verify Netdata is accessible from your machine |
| 245 | - Test: `curl http://YOUR_NETDATA_IP:19999/api/v3/info` |
| 246 | - Check firewall rules allow connection to port 19999 |
| 247 | |
| 248 | ### "Bridge Not Found" Error |
| 249 | |
| 250 | - Verify the nd-mcp path is correct |
| 251 | - Windows users: Include the `.exe` extension |
| 252 | - Ensure Netdata is installed on your local machine (for the bridge) |
| 253 | |
| 254 | ### Limited Access to Data |
| 255 | |
| 256 | - Verify API key is included in the connection string |
| 257 | - Ensure the API key file exists on the Netdata server |
| 258 | - Check that functions and logs collectors are enabled |