| 1 | # Netdata Model Context Protocol (MCP) Integration |
| 2 | |
| 3 | Netdata Agents (and soon Netdata Cloud) provide a Model Context Protocol (MCP) server that enables AI assistants like Claude or Cursos to interact with your infrastructure monitoring data. This integration allows AI assistants to access metrics, logs, alerts, and live system information (processes, services, containers, VMs, network connections, etc), acting as a capable DevOps/SRE/SysAdmin assistant. |
| 4 | |
| 5 | ## Overview |
| 6 | |
| 7 | The AI assistants have different visibility on your infrastructure, depending on where in a Netdata hierarchy they are connected: |
| 8 | |
| 9 | - **Netdata Cloud**: (not yet available) AI assistants connected to Netdata Cloud will have full visibility across all nodes in your infrastructure. |
| 10 | - **Netdata Parent Node**: AI assistants connected to a Netdata parent node will have visibility across all child nodes connected to that parent. |
| 11 | - **Netdata Child Node**: AI assistants connected to a Netdata child node will only have visibility into that specific node. |
| 12 | - **Netdata Standalone Node**: AI assistants connected to a standalone Netdata node will only have visibility into that specific node. |
| 13 | |
| 14 | ## Supported AI Assistants |
| 15 | |
| 16 | You can use Netdata with the following AI assistants: |
| 17 | |
| 18 | - [Claude Desktop](https://claude.ai/download): supports flat-fee usage for unlimited access |
| 19 | - [Claude Code](https://claude.ai/code): supports flat-fee usage for unlimited access |
| 20 | - [Cursor](https://www.cursor.com/): supports flat-fee usage for unlimited access. Enables Netdata use with multiple AI assistants, including Claude, ChatGPT, and Gemini. |
| 21 | |
| 22 | Probably more: Check the [MCP documentation](https://modelcontextprotocol.io/clients) for a full list of supported AI assistants. |
| 23 | |
| 24 | All these AI assistants need local access to the MCP servers. When the client supports **HTTP streamable** or **Server-Sent Events (SSE)** transports (for example, `npx @modelcontextprotocol/remote-mcp`), it can now connect directly to Netdata's `/mcp` (HTTP) or `/sse` endpoints—no custom bridge required. |
| 25 | |
| 26 | Many desktop assistants, however, still talk to MCP servers over `stdio`. For them you still need a bridge that converts `stdio` to a network transport. Netdata keeps shipping the `nd-mcp` bridge (plus the polyglot bridges in `bridges/`) for this purpose. |
| 27 | |
| 28 | Once MCP is integrated into Netdata Cloud, Web-based AI assistants will also be supported. For Web-based AI assistants, the backend of the assistant connects to a publicly accessible MCP server (i.e. Netdata Cloud) to access infrastructure observability data, without needing a bridge. |
| 29 | |
| 30 | ## Installation |
| 31 | |
| 32 | The MCP server is built into Netdata and requires no additional installation. Just ensure you have a recent version of Netdata installed. |
| 33 | |
| 34 | To use the MCP integration of Netdata with AI clients, you need to configure them and bridge them to the Netdata MCP server. |
| 35 | |
| 36 | ## Configuration of AI Assistants |
| 37 | |
| 38 | The configuration of most AI assistants is done via a configuration file, which is almost identical for all of them. |
| 39 | |
| 40 | ```json |
| 41 | { |
| 42 | "mcpServers": { |
| 43 | "netdata": { |
| 44 | "command": "/usr/bin/nd-mcp", |
| 45 | "args": [ |
| 46 | "--bearer", |
| 47 | "YOUR_API_KEY", |
| 48 | "ws://IP_OF_YOUR_NETDATA:19999/mcp" |
| 49 | ] |
| 50 | } |
| 51 | } |
| 52 | } |
| 53 | ``` |
| 54 | |
| 55 | The program `nd-mcp` is still the universal bridge that converts `stdio` communication to network transports. This program is part of all Netdata installations, so by installing Netdata on your personal computer (Linux, macOS, Windows) you will have it available. |
| 56 | |
| 57 | There may be different paths for it, depending on how you installed Netdata: |
| 58 | |
| 59 | - `/usr/bin/nd-mcp` or `/usr/sbin/nd-mcp`: Linux native packages (together with the `netdata` and `netdatacli` commands) |
| 60 | - `/opt/netdata/usr/bin/nd-mcp`: Linux static Netdata installations |
| 61 | - `/usr/local/netdata/usr/bin/nd-mcp`: MacOS installations from source |
| 62 | - `C:\\Program Files\\Netdata\\usr\\bin\\nd-mcp.exe`: Windows installations |
| 63 | |
| 64 | ### Native HTTP/SSE connection (remote-mcp) |
| 65 | |
| 66 | If your client supports HTTP or SSE, you can skip the bridge entirely. The Netdata agent exposes two MCP HTTP endpoints on the same port as the dashboard: |
| 67 | |
| 68 | | Endpoint | Transport | Notes | |
| 69 | | --- | --- | --- | |
| 70 | | `http://IP_OF_YOUR_NETDATA:19999/mcp` | Streamable HTTP (chunked JSON) | Default response; add `Accept: application/json` | |
| 71 | | `http://IP_OF_YOUR_NETDATA:19999/mcp?transport=sse` | Server-Sent Events | Equivalent to sending `Accept: text/event-stream` | |
| 72 | |
| 73 | To test quickly with the official MCP CLI: |
| 74 | |
| 75 | ```bash |
| 76 | npx @modelcontextprotocol/remote-mcp \ |
| 77 | --sse http://IP_OF_YOUR_NETDATA:19999/mcp \ |
| 78 | --header "Authorization: Bearer YOUR_API_KEY" |
| 79 | ``` |
| 80 | |
| 81 | Or, to prefer streamable HTTP: |
| 82 | |
| 83 | ```bash |
| 84 | npx @modelcontextprotocol/remote-mcp \ |
| 85 | --http http://IP_OF_YOUR_NETDATA:19999/mcp \ |
| 86 | --header "Authorization: Bearer YOUR_API_KEY" |
| 87 | ``` |
| 88 | |
| 89 | These commands let you browse the Netdata MCP tools without installing `nd-mcp`. You can still keep `nd-mcp` in your assistant configuration as a fallback for clients that only speak `stdio`. |
| 90 | |
| 91 | You will also need: |
| 92 | |
| 93 | `IP_OF_YOUR_NETDATA`, is the IP address or hostname of the Netdata instance you want to connect to. This will eventually be replaced by the Netdata Cloud URL. For this dev preview, use any Netdata, preferably one of your parent nodes. Remember that the AI assistant will "see" only the nodes that are connected to that Netdata instance. |
| 94 | |
| 95 | `YOUR_API_KEY` is the API key that allows the AI assistant to access sensitive functions like logs and live system information. Just start Netdata and it will automatically generate a random UUID for you. You can find it at: |
| 96 | |
| 97 | ``` |
| 98 | /var/lib/netdata/mcp_dev_preview_api_key |
| 99 | ``` |
| 100 | |
| 101 | or, if you installed a static Netdata package, it may be located at: |
| 102 | |
| 103 | ``` |
| 104 | /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key |
| 105 | ``` |
| 106 | |
| 107 | |
| 108 | To view your API key: |
| 109 | ```bash |
| 110 | sudo cat /var/lib/netdata/mcp_dev_preview_api_key |
| 111 | ``` |
| 112 | |
| 113 | or |
| 114 | |
| 115 | ```bash |
| 116 | sudo cat /opt/netdata/var/lib/netdata/mcp_dev_preview_api_key |
| 117 | ``` |
| 118 | |
| 119 | ### Claude Desktop |
| 120 | |
| 121 | To add Netdata MCP to Claude Desktop: |
| 122 | |
| 123 | 1. Open Claude Desktop |
| 124 | 2. Navigate to the Developer settings: |
| 125 | - **Windows/Linux**: File → Settings → Developer (or use Ctrl+,) |
| 126 | - **macOS**: Claude → Settings → Developer (or use Cmd+,) |
| 127 | 3. Click the "Edit Config" button (below the server list) |
| 128 | 4. This will open or show the exact configuration file location |
| 129 | 5. Add the configuration mentioned above to that file. |
| 130 | |
| 131 | **Linux Users**: Claude Desktop is available via a community project (https://github.com/fsoft72/claude-desktop-to-appimage). It works best with https://github.com/TheAssassin/AppImageLauncher. |
| 132 | |
| 133 | Once configured correctly, you will need to restart Claude Desktop. |
| 134 | Once restarted, you should see "netdata" appear in Claude Desktop: |
| 135 | - Click the "Search and tools" button (just below the prompt) |
| 136 | - You should see "netdata" listed among the available tools |
| 137 | - If you don't see it, check your configuration and ensure the bridge is accessible |
| 138 | |
| 139 | ### Claude Code |
| 140 | |
| 141 | For [Claude Code](https://claude.ai/code), add to your project's root, the file `.mcp.json`, with the contents given above. This file will be automatically detected by Claude Code the next time it starts in that directory. |
| 142 | |
| 143 | Alternatively, you can add it using a Claude CLI command like this: |
| 144 | |
| 145 | ```bash |
| 146 | claude mcp add netdata /usr/bin/nd-mcp --bearer YOUR_API_KEY ws://IP_OF_YOUR_NETDATA:19999/mcp |
| 147 | ``` |
| 148 | |
| 149 | Once configured correctly, run `claude mcp list` or you can issue the command `/mcp` to your Claude Code. It should show you the available MCP servers, including "netdata". |
| 150 | |
| 151 | ### Cursor |
| 152 | |
| 153 | For [Cursor](https://www.cursor.com/), add the configuration to the MCP settings. |
| 154 | |
| 155 | ## Alternative `stdio` to `websocket` Bridges |
| 156 | These bridges remain useful for AI assistants that only support `stdio`. If your tooling can use Netdata's native HTTP/SSE endpoints you can skip this section. |
| 157 | |
| 158 | We provide 3 different bridges for you to choose the one that best fits your environment: |
| 159 | |
| 160 | 1. **Go bridge**: Located at `src/web/mcp/bridges/stdio-golang/` |
| 161 | 2. **Node.js bridge**: Located at `src/web/mcp/bridges/stdio-nodejs/` |
| 162 | 3. **Python bridge**: Located at `src/web/mcp/bridges/stdio-python/` |
| 163 | |
| 164 | All these bridges should provide exactly the same functionality, so you can choose the one that best fits your environment. |
| 165 | |
| 166 | Each of these directories includes `build.sh` script to install dependencies and prepare the bridge. |
| 167 | The Go bridge provides also a `build.bat` script for Windows users. |
| 168 | |
| 169 | ## Capabilities |
| 170 | |
| 171 | The MCP integration provides AI assistants with access to: |
| 172 | |
| 173 | ### Infrastructure Discovery |
| 174 | - **Nodes information**: Complete visibility across all connected nodes in your infrastructure |
| 175 | - Hardware specifications, OS details, virtualization info |
| 176 | - Streaming configuration and parent-child relationships |
| 177 | - Connection status and data collection capabilities |
| 178 | - **Metrics discovery**: All metrics collected by your Netdata installation |
| 179 | - System metrics: CPU, memory, disks, network interfaces |
| 180 | - Application metrics: databases, web servers, containers |
| 181 | - Hardware metrics: IPMI sensors, GPU, temperature sensors |
| 182 | - Custom metrics: StatsD, logs-based metrics |
| 183 | |
| 184 | ### Metrics and Analytics |
| 185 | - **Time-series queries**: Powerful data aggregation and analysis |
| 186 | - Multiple grouping options: by dimension, instance, node, or label |
| 187 | - Aggregation methods: sum, average, min, max, percentages |
| 188 | - Time aggregations: average, min, max, median, percentile, etc. |
| 189 | - **Anomaly detection**: ML-powered anomaly detection across all metrics |
| 190 | - Real-time anomaly rates (0-100% of time anomalous) |
| 191 | - Per-metric and per-dimension anomaly tracking |
| 192 | - **Correlation analysis**: Find metrics that changed during incidents |
| 193 | - Compare problem periods with baseline periods |
| 194 | - Statistical and volume-based correlation methods |
| 195 | - **Variability analysis**: Identify unstable or fluctuating metrics |
| 196 | |
| 197 | ### Live System Information (requires API key and claimed agent) |
| 198 | - **Processes**: Detailed process information including: |
| 199 | - CPU usage, memory consumption, I/O statistics |
| 200 | - File descriptors, page faults, parent-child relationships |
| 201 | - Container-aware process tracking |
| 202 | - **Network connections**: Active connections with: |
| 203 | - Protocol details, states, addresses, ports |
| 204 | - Performance metrics per connection |
| 205 | - **Systemd services & units**: Service health and resource usage |
| 206 | - **Mount points**: Filesystem usage, capacity, and inode statistics |
| 207 | - **Block devices**: I/O performance, latency, and utilization |
| 208 | - **Containers & VMs**: Resource usage across containerized workloads |
| 209 | - **Network interfaces**: Traffic rates, packets, drops, link status |
| 210 | - **Streaming status**: Real-time replication and ML synchronization |
| 211 | |
| 212 | ### Logs Access (requires API key and claimed agent) |
| 213 | - **systemd-journal**: Comprehensive log access including: |
| 214 | - Local system logs, user logs, and namespaces |
| 215 | - Remote system logs from connected nodes |
| 216 | - Advanced filtering and search capabilities |
| 217 | - Historical log data based on retention |
| 218 | - **Windows events**: Query Windows event logs (on Windows systems) |
| 219 | |
| 220 | ### Alerts and Monitoring |
| 221 | - **Active alerts**: Currently raised warnings and critical alerts |
| 222 | - Detailed alert information including values, timestamps, and context |
| 223 | - Alert classification by type, component, and severity |
| 224 | - **Alert history**: Complete alert state tracking |
| 225 | - All states: critical, warning, clear, undefined, uninitialized |
| 226 | - Alert transitions with timestamps and values |
| 227 | - **Alert metadata**: Recipients, configurations, and thresholds |
| 228 | |
| 229 | ### Available Metric Categories |
| 230 | The integration provides access to all metrics categories collected by Netdata including: |
| 231 | - Core system: CPU, memory, disks, network, processes |
| 232 | - Containers: Docker, cgroups, systemd services |
| 233 | - Databases: MySQL, PostgreSQL, Redis, MongoDB |
| 234 | - Web servers: Apache, Nginx, LiteSpeed |
| 235 | - Hardware: IPMI, GPUs, temperature sensors, SMART |
| 236 | - Network services: DNS, DHCP, VPN, firewalls |
| 237 | - Applications: Custom StatsD metrics, logs-based metrics |
| 238 | - And any other metrics collected by your Netdata installation |
| 239 | |
| 240 | ## Security Considerations |
| 241 | |
| 242 | - The MCP integration currently provides **read-only** access to Netdata |
| 243 | - Dynamic configuration is not exposed - AI assistants cannot read or modify Netdata settings |
| 244 | - API key is required for accessing sensitive functions (logs and live data) |
| 245 | - For production use, ensure your Netdata agent is claimed to Netdata Cloud |
| 246 | |
| 247 | ## Usage Examples |
| 248 | |
| 249 | Once configured, you can ask questions like: |
| 250 | |
| 251 | ### Infrastructure Overview |
| 252 | - "Show me all connected nodes and their status" |
| 253 | - "What metrics are available for my database servers?" |
| 254 | - "Provide an observability coverage report for my infrastructure" |
| 255 | - "Which nodes are offline or having connection issues?" |
| 256 | |
| 257 | ### Performance Analysis |
| 258 | - "What are the top CPU-consuming processes across all my servers?" |
| 259 | - "Show me network interface utilization across all nodes" |
| 260 | - "What's the memory usage trend for my database servers?" |
| 261 | - "List all block devices and their I/O performance" |
| 262 | - "Which of my nodes have disk backlog issues?" |
| 263 | - "Show me container resource usage statistics" |
| 264 | |
| 265 | ### Anomaly Detection and Troubleshooting |
| 266 | - "Which metrics are showing anomalous behavior in the last hour?" |
| 267 | - "Find metrics that changed significantly during the outage at 2 PM" |
| 268 | - "What are the most unstable metrics in my infrastructure?" |
| 269 | - "Analyze the correlation between disk I/O and application response time" |
| 270 | |
| 271 | ### Alerts and Monitoring |
| 272 | - "Are there any critical alerts currently active?" |
| 273 | - "Show me all alert transitions in the last 24 hours" |
| 274 | - "Which systems have disk space warnings?" |
| 275 | - "What alerts fired and cleared during the night?" |
| 276 | |
| 277 | ### System Logs and Events |
| 278 | - "Show me systemd journal logs for failed services" |
| 279 | - "Search for authentication failures in the last hour" |
| 280 | - "Display kernel errors from all nodes" |
| 281 | - "Find all logs related to out-of-memory conditions" |
| 282 | |
| 283 | ### Live System State |
| 284 | - "List all systemd services and their status" |
| 285 | - "Show me active network connections on the web servers" |
| 286 | - "What's the current streaming replication status?" |
| 287 | - "Display mount points with low available space" |
| 288 | |
| 289 | ## Troubleshooting |
| 290 | |
| 291 | 1. **Connection refused**: Ensure Netdata is running and accessible at the specified URL |
| 292 | 2. **Bridge not found**: Verify the bridge path is correct and dependencies are installed |
| 293 | 3. **Authentication errors**: Verify the API key is correct and the agent is claimed |
| 294 | 4. **Missing data**: Check that the Netdata agent has the required collectors enabled |
| 295 | 5. **Limited access**: Without API key or unclaimed agent, functions and logs won't be available |
| 296 | |
| 297 | ## FAQ |
| 298 | |
| 299 | - **Q: Can I use MCP with other AI assistants?** |
| 300 | - A: Yes, MCP supports multiple AI assistants. Check the [MCP documentation](https://modelcontextprotocol.io/clients) for a full list. |
| 301 | |
| 302 | - **Q: Do I need to run a bridge on my local machine?** |
| 303 | - A: Only if your client speaks `stdio` (Claude Desktop, Cursor, etc). Modern MCP clients such as `npx @modelcontextprotocol/remote-mcp` can talk HTTP/SSE directly to Netdata's `/mcp` endpoints, so no bridge is required in that case. Keep `nd-mcp` as a fallback for assistants that still require `stdio`. |
| 304 | |
| 305 | - **Q: How do I find my API key?** |
| 306 | - A: The API key is automatically generated by Netdata and stored in `/var/lib/netdata/mcp_dev_preview_api_key` or `/opt/netdata/var/lib/netdata/mcp_dev_preview_api_key` on the Netdata Agent you will connect to. Use `sudo cat` to view it. |
| 307 | |
| 308 | - **Q: Can I use MCP with Netdata Cloud?** |
| 309 | - A: Yes, once MCP is integrated into Netdata Cloud, you will be able to use it with web-based AI assistants without needing a bridge. |
| 310 | |
| 311 | - **Q: What data can I access with MCP?** |
| 312 | - A: You can access metrics, logs, alerts, live system information (processes, services, containers, network connections), and more. |
| 313 | |
| 314 | - **Q: Can I use MCP with my existing Netdata installation?** |
| 315 | - A: Yes, as long as you have a recent version of Netdata installed, you can use the MCP integration without any additional installation. |
| 316 | |
| 317 | - **Q: Is MCP secure?** |
| 318 | - A: Yes, MCP currently provides read-only access. Sensitive functions like logs and live system information require an API key, and the agent should be claimed to Netdata Cloud for production use. |
| 319 | |
| 320 | - **Q: Will my observability data be exposed to AI companies?** |
| 321 | - A: Yes, but it depends on the AI assistant you use and the subscription you have. For example, Claude promises that your data will not be used to train their models for certain subscriptions, and Cursor allows you to use multiple AI assistants. Always check the privacy policies of the AI assistant you choose. |
| 322 | |
| 323 | - **Q: Are the responses of AI assistants accurate?** |
| 324 | - A: AI assistants like Claude are designed to provide accurate and relevant responses based on the data they have access to. However, they may not always be perfect, or they may have not checked all the aspects before giving answers. It's important to verify critical information. |
| 325 | |
| 326 | ## Best Practices |
| 327 | |
| 328 | ### AI Assistants sampling data |
| 329 | |
| 330 | Sometimes, when you ask generic questions about your infrastructure, AI assistants do a simple sampling on a few nodes of the infrastructure, instead of querying all nodes. In Netdata we have provided the tools to properly do that, but AI assistants may not use them. |
| 331 | |
| 332 | Examples: |
| 333 | |
| 334 | Q: "which are the top processes/containers/VMs/services running on my servers?" |
| 335 | |
| 336 | The AI assistant may respond with a list of processes/containers/VMs/services from a few nodes, instead of querying all nodes. |
| 337 | |
| 338 | The proper way in Netdata is to query: |
| 339 | |
| 340 | - `app.*` charts/contexts for `processes`, which will return the processes running on all nodes grouped by category. |
| 341 | - `systemd.*` to get the services running on all nodes. |
| 342 | - `cgroup.*` to get the all the containers and VMs on all nodes. |
| 343 | |
| 344 | For all such queries, Netdata responses return cardinality information (much like the NIDL charts on your Netdata dashboard), so the AI assistant could get a much better picture instead of sampling data. When you notice that, you could ask the AI assistant to find the answer using more generic queries. |
| 345 | |
| 346 | ### AI Assistants missing newer Netdata features |
| 347 | |
| 348 | Sometimes you ask AI assistants about features that have been recently added to Netdata (eg logs, or windows capabilities), and the AI assistant instead of checking what is available via their MCP connection, they say that Netdata does not support that feature. Answering "check your MCP tools, features, functions" is usually enough for the AI assistant to check the available features and start using them. |
| 349 | |
| 350 | ### AI Assistants not using MCP at all |
| 351 | |
| 352 | Sometimes you need instruct them to use their MCP connection. So instead of saying "check the performance of my production db", you can say "use netdata to check the performance of my production db". This way, the AI assistant will use its MCP connection to query the Netdata instance and provide you with the relevant information. |
| 353 | |
| 354 | ### Use AI Assistants to do your DevOps/SRE/SysAdmin "laundry" |
| 355 | |
| 356 | Our advice is to use AI assistants to do "your laundry": Give them specific tasks, check the queries they did to get that information, and when possible ask them to cross-check their answers using a different tool/source. AI assistants usually rush to make conclusions, so **challenge them** and they will go deeper and correct themselves. Remember that you always need to verify their answers, especially for critical tasks. |
| 357 | |
| 358 | ### Multiple Netdata MCP servers for a single AI assistant |
| 359 | |
| 360 | If you need to configure multiple MCP servers, you can add them under the `mcpServers` section with different names. Example: |
| 361 | |
| 362 | ```json |
| 363 | { |
| 364 | "mcpServers": { |
| 365 | "netdata-production": { |
| 366 | "command": "/usr/bin/nd-mcp", |
| 367 | "args": [ |
| 368 | "--bearer", |
| 369 | "YOUR_API_KEY", |
| 370 | "ws://IP_OF_YOUR_NETDATA:19999/mcp" |
| 371 | ] |
| 372 | }, |
| 373 | "netdata-testing": { |
| 374 | "command": "/usr/bin/nd-mcp", |
| 375 | "args": [ |
| 376 | "--bearer", |
| 377 | "YOUR_API_KEY", |
| 378 | "ws://IP_OF_YOUR_NETDATA:19999/mcp" |
| 379 | ] |
| 380 | } |
| 381 | } |
| 382 | } |
| 383 | ``` |
| 384 | |
| 385 | However, when multiple netdata MCP servers are configured, all AI assistants have difficulties to determine which one to use: |
| 386 | |
| 387 | - **Claude Desktop**: it seems there is no way to instruct it to use the right one. There is an enable/disable toggle for each MCP server, which however does not work properly. So, it is best to configure only one MCP server at a time. |
| 388 | - **Cursor**: Similarly, it is impossible to instruct it to use the right one. However, there is a toggle and it works properly, but you still need to ensure that the Netdata server you want to use is the only one enabled. |
| 389 | - **Claude Code**: this project has a different philosophy: you can have a different `.mcp.json` file in each project directory (the current directory from which you run it), so you can have different configurations for each project/directory. Since **Claude Code** also supports a `Claude.md` file with default instructions to the AI assistant, you can have different directories with different instructions and configurations, so you can use multiple Netdata MCP servers by spawning multiple Claude Code instances in different directories. |
| 390 | |
| 391 | For more information about Netdata, visit [netdata.cloud](https://netdata.cloud) |