| 1 | # Crush |
| 2 | |
| 3 | Configure Crush by Charmbracelet to access your Netdata infrastructure through MCP for glamorous terminal-based AI operations. |
| 4 | |
| 5 | ## Transport Support |
| 6 | |
| 7 | Crush has comprehensive MCP transport support, making it highly flexible for connecting to Netdata: |
| 8 | |
| 9 | | Transport | Support | Netdata Version | Use Case | |
| 10 | |-----------|---------|-----------------|----------| |
| 11 | | **stdio** (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket | |
| 12 | | **Streamable HTTP** | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) | |
| 13 | | **SSE** (Server-Sent Events) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's SSE endpoint | |
| 14 | | **WebSocket** | ❌ Not Supported | - | Use nd-mcp bridge or HTTP/SSE instead | |
| 15 | |
| 16 | ## Prerequisites |
| 17 | |
| 18 | 1. **Crush installed** - Available via npm, Homebrew, or direct download from [GitHub](https://github.com/charmbracelet/crush) |
| 19 | 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). |
| 20 | - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge |
| 21 | - **v2.7.2+**: Direct HTTP/SSE support available (recommended) |
| 22 | 3. **For WebSocket or stdio connections: `nd-mcp` bridge** - The stdio-to-websocket bridge. [Find its absolute path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge). Not needed for direct HTTP/SSE connections on v2.7.2+. |
| 23 | 4. **Optionally, the Netdata MCP API key** that unlocks full access to sensitive observability data (protected functions, full access to logs) on your Netdata. 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) |
| 24 | |
| 25 | > Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching Crush so credentials never appear in command-line arguments or config files: |
| 26 | > ```bash |
| 27 | > export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)" |
| 28 | > ``` |
| 29 | |
| 30 | ## Installation |
| 31 | |
| 32 | Install Crush using one of these methods: |
| 33 | |
| 34 | ```bash |
| 35 | # Homebrew (recommended for macOS) |
| 36 | brew install charmbracelet/tap/crush |
| 37 | |
| 38 | # NPM |
| 39 | npm install -g @charmland/crush |
| 40 | |
| 41 | # Arch Linux |
| 42 | yay -S crush-bin |
| 43 | |
| 44 | # Windows (Winget) |
| 45 | winget install charmbracelet.crush |
| 46 | |
| 47 | # Windows (Scoop) |
| 48 | scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git |
| 49 | scoop install crush |
| 50 | |
| 51 | # Or install with Go |
| 52 | go install github.com/charmbracelet/crush@latest |
| 53 | ``` |
| 54 | |
| 55 | ## Configuration Methods |
| 56 | |
| 57 | Crush uses JSON configuration files with the following priority: |
| 58 | 1. `.crush.json` (project-specific) |
| 59 | 2. `crush.json` (project-specific) |
| 60 | 3. `~/.config/crush/crush.json` (global) |
| 61 | |
| 62 | ### Netdata Cloud MCP |
| 63 | |
| 64 | Connect to your entire Netdata Cloud infrastructure |
| 65 | through a single endpoint — no local setup, bridges, |
| 66 | or firewall changes needed. |
| 67 | |
| 68 | **Prerequisites:** |
| 69 | |
| 70 | - Netdata Cloud account with a Paid plan |
| 71 | - Nodes claimed to Netdata Cloud |
| 72 | - API token with `scope:mcp` |
| 73 | ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md)) |
| 74 | |
| 75 | ```json |
| 76 | { |
| 77 | "$schema": "https://charm.land/crush.json", |
| 78 | "mcp": { |
| 79 | "netdata-cloud": { |
| 80 | "type": "http", |
| 81 | "url": "https://app.netdata.cloud/api/v1/mcp", |
| 82 | "headers": { |
| 83 | "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN" |
| 84 | }, |
| 85 | "timeout": 120, |
| 86 | "disabled": false |
| 87 | } |
| 88 | } |
| 89 | } |
| 90 | ``` |
| 91 | |
| 92 | Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your |
| 93 | Netdata Cloud API token (must have `scope:mcp`). |
| 94 | For more details, see |
| 95 | [Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp). |
| 96 | |
| 97 | ### Local Agent or Parent |
| 98 | |
| 99 | The following methods connect directly to a Netdata Agent or Parent on your network. |
| 100 | |
| 101 | #### Method 1: Direct HTTP Connection (Recommended for v2.7.2+) |
| 102 | |
| 103 | Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge: |
| 104 | |
| 105 | ```json |
| 106 | { |
| 107 | "$schema": "https://charm.land/crush.json", |
| 108 | "mcp": { |
| 109 | "netdata": { |
| 110 | "type": "http", |
| 111 | "url": "http://YOUR_NETDATA_IP:19999/mcp", |
| 112 | "headers": { |
| 113 | "Authorization": "Bearer NETDATA_MCP_API_KEY" |
| 114 | }, |
| 115 | "timeout": 120, |
| 116 | "disabled": false |
| 117 | } |
| 118 | } |
| 119 | } |
| 120 | ``` |
| 121 | |
| 122 | For HTTPS connections: |
| 123 | |
| 124 | ```json |
| 125 | { |
| 126 | "$schema": "https://charm.land/crush.json", |
| 127 | "mcp": { |
| 128 | "netdata": { |
| 129 | "type": "http", |
| 130 | "url": "https://YOUR_NETDATA_IP:19999/mcp", |
| 131 | "headers": { |
| 132 | "Authorization": "Bearer NETDATA_MCP_API_KEY" |
| 133 | }, |
| 134 | "timeout": 120 |
| 135 | } |
| 136 | } |
| 137 | } |
| 138 | ``` |
| 139 | |
| 140 | #### Method 2: Direct SSE Connection (v2.7.2+) |
| 141 | |
| 142 | Connect directly to Netdata's SSE endpoint for real-time streaming: |
| 143 | |
| 144 | ```json |
| 145 | { |
| 146 | "$schema": "https://charm.land/crush.json", |
| 147 | "mcp": { |
| 148 | "netdata": { |
| 149 | "type": "sse", |
| 150 | "url": "http://YOUR_NETDATA_IP:19999/mcp?transport=sse", |
| 151 | "headers": { |
| 152 | "Authorization": "Bearer NETDATA_MCP_API_KEY" |
| 153 | }, |
| 154 | "timeout": 120, |
| 155 | "disabled": false |
| 156 | } |
| 157 | } |
| 158 | } |
| 159 | ``` |
| 160 | |
| 161 | #### Method 3: Using nd-mcp Bridge (stdio) |
| 162 | |
| 163 | For environments where you prefer or need to use the bridge: |
| 164 | |
| 165 | ```json |
| 166 | { |
| 167 | "$schema": "https://charm.land/crush.json", |
| 168 | "mcp": { |
| 169 | "netdata": { |
| 170 | "type": "stdio", |
| 171 | "command": "/usr/sbin/nd-mcp", |
| 172 | "args": ["ws://YOUR_NETDATA_IP:19999/mcp"], |
| 173 | "timeout": 120, |
| 174 | "disabled": false |
| 175 | } |
| 176 | } |
| 177 | } |
| 178 | ``` |
| 179 | |
| 180 | #### Method 4: Using npx mcp-remote (Alternative Bridge for v2.7.2+) |
| 181 | |
| 182 | If nd-mcp is not available, use the official MCP remote client (requires Netdata v2.7.2+). For detailed options and troubleshooting, see [Using MCP Remote Client](/docs/netdata-ai/mcp/README.md#using-mcp-remote-client). |
| 183 | |
| 184 | ```json |
| 185 | { |
| 186 | "$schema": "https://charm.land/crush.json", |
| 187 | "mcp": { |
| 188 | "netdata": { |
| 189 | "type": "stdio", |
| 190 | "command": "npx", |
| 191 | "args": [ |
| 192 | "mcp-remote@latest", |
| 193 | "--http", |
| 194 | "http://YOUR_NETDATA_IP:19999/mcp", |
| 195 | "--allow-http", |
| 196 | "--header", |
| 197 | "Authorization: Bearer NETDATA_MCP_API_KEY" |
| 198 | ], |
| 199 | "timeout": 120 |
| 200 | } |
| 201 | } |
| 202 | } |
| 203 | ``` |
| 204 | |
| 205 | ## Environment Variables |
| 206 | |
| 207 | Crush supports environment variable expansion using `$(echo $VAR)` syntax: |
| 208 | |
| 209 | ```json |
| 210 | { |
| 211 | "$schema": "https://charm.land/crush.json", |
| 212 | "mcp": { |
| 213 | "netdata": { |
| 214 | "type": "http", |
| 215 | "url": "http://YOUR_NETDATA_IP:19999/mcp", |
| 216 | "headers": { |
| 217 | "Authorization": "Bearer $(echo $NETDATA_API_KEY)" |
| 218 | }, |
| 219 | "timeout": 120 |
| 220 | } |
| 221 | } |
| 222 | } |
| 223 | ``` |
| 224 | |
| 225 | ## Project-Based Configuration |
| 226 | |
| 227 | Create project-specific configurations by placing `.crush.json` or `crush.json` in your project root: |
| 228 | |
| 229 | ```json |
| 230 | { |
| 231 | "$schema": "https://charm.land/crush.json", |
| 232 | "mcp": { |
| 233 | "netdata-prod": { |
| 234 | "type": "http", |
| 235 | "url": "https://prod-parent.company.com:19999/mcp", |
| 236 | "headers": { |
| 237 | "Authorization": "Bearer $(echo $PROD_API_KEY)" |
| 238 | }, |
| 239 | "timeout": 120 |
| 240 | }, |
| 241 | "netdata-staging": { |
| 242 | "type": "sse", |
| 243 | "url": "https://staging-parent.company.com:19999/mcp?transport=sse", |
| 244 | "headers": { |
| 245 | "Authorization": "Bearer $(echo $STAGING_API_KEY)" |
| 246 | }, |
| 247 | "timeout": 120 |
| 248 | } |
| 249 | } |
| 250 | } |
| 251 | ``` |
| 252 | |
| 253 | Replace in all examples: |
| 254 | - `YOUR_NETDATA_IP` - IP address or hostname of your Netdata Agent/Parent |
| 255 | - `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key) |
| 256 | - `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge) (stdio method only) |
| 257 | |
| 258 | ## How to Use |
| 259 | |
| 260 | Once configured, start Crush and it will automatically connect to your Netdata MCP servers: |
| 261 | |
| 262 | ```bash |
| 263 | # Start Crush |
| 264 | crush |
| 265 | |
| 266 | # Ask infrastructure questions |
| 267 | What's the current CPU usage across all servers? |
| 268 | Show me any performance anomalies in the last hour |
| 269 | Which services are consuming the most resources? |
| 270 | ``` |
| 271 | |
| 272 | ## Tool Permissions |
| 273 | |
| 274 | Crush asks for permission before running tools by default. You can pre-approve certain Netdata tools: |
| 275 | |
| 276 | ```json |
| 277 | { |
| 278 | "$schema": "https://charm.land/crush.json", |
| 279 | "permissions": { |
| 280 | "allowed_tools": [ |
| 281 | "mcp_netdata_list_metrics", |
| 282 | "mcp_netdata_query_metrics", |
| 283 | "mcp_netdata_list_nodes", |
| 284 | "mcp_netdata_list_alerts" |
| 285 | ] |
| 286 | } |
| 287 | } |
| 288 | ``` |
| 289 | |
| 290 | > **⚠️ Warning:** Use the `--yolo` flag to bypass all permission prompts, but be extremely careful with this feature. |
| 291 | |
| 292 | ## Example Workflows |
| 293 | |
| 294 | **Performance Investigation:** |
| 295 | ``` |
| 296 | Investigate why our application response times increased this afternoon using Netdata metrics |
| 297 | ``` |
| 298 | |
| 299 | **Resource Optimization:** |
| 300 | ``` |
| 301 | Check memory usage patterns across all nodes and suggest optimization strategies |
| 302 | ``` |
| 303 | |
| 304 | **Alert Analysis:** |
| 305 | ``` |
| 306 | Explain the current active alerts from Netdata and their potential impact |
| 307 | ``` |
| 308 | |
| 309 | **Anomaly Detection:** |
| 310 | ``` |
| 311 | Find any anomalous metrics in the last 2 hours and explain what might be causing them |
| 312 | ``` |
| 313 | |
| 314 | > **💡 Advanced Usage:** Crush can combine observability data with its terminal-based interface for powerful DevOps workflows. Learn about the opportunities and security considerations in [AI DevOps Copilot](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md). |
| 315 | |
| 316 | ## Troubleshooting |
| 317 | |
| 318 | ### MCP Server Not Connecting |
| 319 | |
| 320 | - Verify Netdata is accessible: `curl http://YOUR_NETDATA_IP:19999/api/v3/info` |
| 321 | - Check the JSON syntax in your configuration file |
| 322 | - Ensure the MCP server is not disabled (`"disabled": false`) |
| 323 | |
| 324 | ### Connection Timeouts |
| 325 | |
| 326 | - Increase the `timeout` value in your configuration (default is 120 seconds) |
| 327 | - Check network connectivity between Crush and Netdata |
| 328 | - Verify firewall rules allow access to port 19999 |
| 329 | |
| 330 | ### Limited Data Access |
| 331 | |
| 332 | - Verify API key is included in the connection URL or headers |
| 333 | - Check that the Netdata agent is properly configured for MCP |
| 334 | - Ensure MCP is enabled in your Netdata build |
| 335 | |
| 336 | ### Environment Variable Issues |
| 337 | |
| 338 | - Crush uses `$(echo $VAR)` syntax, not `$VAR` or `${VAR}` |
| 339 | - Ensure environment variables are exported before starting Crush |
| 340 | - Test with `echo $NETDATA_API_KEY` to verify the variable is set |
| 341 | |
| 342 | ## Advanced Configuration |
| 343 | |
| 344 | ### Multiple Environments with Different Transports |
| 345 | |
| 346 | Configure different Netdata instances using different transport methods: |
| 347 | |
| 348 | ```json |
| 349 | { |
| 350 | "$schema": "https://charm.land/crush.json", |
| 351 | "mcp": { |
| 352 | "netdata-local": { |
| 353 | "type": "stdio", |
| 354 | "command": "/usr/sbin/nd-mcp", |
| 355 | "args": ["ws://localhost:19999/mcp"], |
| 356 | "timeout": 60 |
| 357 | }, |
| 358 | "netdata-parent": { |
| 359 | "type": "http", |
| 360 | "url": "https://parent.company.com:19999/mcp", |
| 361 | "headers": { |
| 362 | "Authorization": "Bearer ${PARENT_API_KEY}" |
| 363 | }, |
| 364 | "timeout": 180 |
| 365 | }, |
| 366 | "netdata-streaming": { |
| 367 | "type": "sse", |
| 368 | "url": "https://stream-parent.company.com:19999/mcp?transport=sse", |
| 369 | "headers": { |
| 370 | "Authorization": "Bearer ${STREAM_API_KEY}" |
| 371 | }, |
| 372 | "timeout": 300 |
| 373 | } |
| 374 | } |
| 375 | } |
| 376 | ``` |
| 377 | |
| 378 | > ℹ️ Before switching between environments, export `ND_MCP_BEARER_TOKEN` with the matching key so the bridge authenticates without exposing credentials in the JSON file. |
| 379 | |
| 380 | ### Debugging MCP Connections |
| 381 | |
| 382 | Enable debug logging to troubleshoot MCP issues: |
| 383 | |
| 384 | ```json |
| 385 | { |
| 386 | "$schema": "https://charm.land/crush.json", |
| 387 | "options": { |
| 388 | "debug": true |
| 389 | } |
| 390 | } |
| 391 | ``` |
| 392 | |
| 393 | View logs: |
| 394 | ```bash |
| 395 | # View recent logs |
| 396 | crush logs |
| 397 | |
| 398 | # Follow logs in real-time |
| 399 | crush logs --follow |
| 400 | ``` |
| 401 | |
| 402 | ## Documentation Links |
| 403 | |
| 404 | - [Crush GitHub Repository](https://github.com/charmbracelet/crush) |
| 405 | - [Crush Configuration Schema](https://charm.land/crush.json) |
| 406 | - [Charmbracelet Documentation](https://charm.sh) |
| 407 | - [Netdata MCP Setup](/docs/netdata-ai/mcp/README.md) |
| 408 | - [AI DevOps Best Practices](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md) |