Crush
Configure Crush by Charmbracelet to access your Netdata infrastructure through MCP for glamorous terminal-based AI operations.
Transport Support
Crush has comprehensive MCP transport support, making it highly flexible for connecting to Netdata:
Transport | Support | Netdata Version | Use Case |
---|---|---|---|
stdio (via nd-mcp bridge) | ✅ Fully Supported | v2.6.0+ | Local bridge to WebSocket |
Streamable HTTP | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's HTTP endpoint (recommended) |
SSE (Server-Sent Events) | ✅ Fully Supported | v2.7.2+ | Direct connection to Netdata's SSE endpoint |
WebSocket | ❌ Not Supported | - | Use nd-mcp bridge or HTTP/SSE instead |
Prerequisites
- Crush installed - Available via npm, Homebrew, or direct download from GitHub
- 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).
- v2.6.0 - v2.7.1: Only WebSocket transport available, requires
nd-mcp
bridge - v2.7.2+: Direct HTTP/SSE support available (recommended)
- v2.6.0 - v2.7.1: Only WebSocket transport available, requires
- For WebSocket or stdio connections:
nd-mcp
bridge - The stdio-to-websocket bridge. Find its absolute path. Not needed for direct HTTP/SSE connections on v2.7.2+. - 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
Export
ND_MCP_BEARER_TOKEN
with your MCP key before launching Crush so credentials never appear in command-line arguments or config files:export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
Installation
Install Crush using one of these methods:
# Homebrew (recommended for macOS)
brew install charmbracelet/tap/crush
# NPM
npm install -g @charmland/crush
# Arch Linux
yay -S crush-bin
# Windows (Winget)
winget install charmbracelet.crush
# Windows (Scoop)
scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
scoop install crush
# Or install with Go
go install github.com/charmbracelet/crush@latest
Configuration Methods
Crush uses JSON configuration files with the following priority:
.crush.json
(project-specific)crush.json
(project-specific)~/.config/crush/crush.json
(global)
Method 1: Direct HTTP Connection (Recommended for v2.7.2+)
Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "http",
"url": "http://YOUR_NETDATA_IP:19999/mcp",
"headers": {
"Authorization": "Bearer NETDATA_MCP_API_KEY"
},
"timeout": 120,
"disabled": false
}
}
}
For HTTPS connections:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "http",
"url": "https://YOUR_NETDATA_IP:19999/mcp",
"headers": {
"Authorization": "Bearer NETDATA_MCP_API_KEY"
},
"timeout": 120
}
}
}
Method 2: Direct SSE Connection (v2.7.2+)
Connect directly to Netdata's SSE endpoint for real-time streaming:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "sse",
"url": "http://YOUR_NETDATA_IP:19999/mcp?transport=sse",
"headers": {
"Authorization": "Bearer NETDATA_MCP_API_KEY"
},
"timeout": 120,
"disabled": false
}
}
}
Method 3: Using nd-mcp Bridge (stdio)
For environments where you prefer or need to use the bridge:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "stdio",
"command": "/usr/sbin/nd-mcp",
"args": ["ws://YOUR_NETDATA_IP:19999/mcp"],
"timeout": 120,
"disabled": false
}
}
}
Method 4: Using npx remote-mcp (Alternative Bridge for v2.7.2+)
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.
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "stdio",
"command": "npx",
"args": [
"mcp-remote@latest",
"--http",
"http://YOUR_NETDATA_IP:19999/mcp",
"--allow-http",
"--header",
"Authorization: Bearer NETDATA_MCP_API_KEY"
],
"timeout": 120
}
}
}
Environment Variables
Crush supports environment variable expansion using $(echo $VAR)
syntax:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata": {
"type": "http",
"url": "http://YOUR_NETDATA_IP:19999/mcp",
"headers": {
"Authorization": "Bearer $(echo $NETDATA_API_KEY)"
},
"timeout": 120
}
}
}
Project-Based Configuration
Create project-specific configurations by placing .crush.json
or crush.json
in your project root:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata-prod": {
"type": "http",
"url": "https://prod-parent.company.com:19999/mcp",
"headers": {
"Authorization": "Bearer $(echo $PROD_API_KEY)"
},
"timeout": 120
},
"netdata-staging": {
"type": "sse",
"url": "https://staging-parent.company.com:19999/mcp?transport=sse",
"headers": {
"Authorization": "Bearer $(echo $STAGING_API_KEY)"
},
"timeout": 120
}
}
}
Replace in all examples:
YOUR_NETDATA_IP
- IP address or hostname of your Netdata Agent/ParentNETDATA_MCP_API_KEY
- Your Netdata MCP API key/usr/sbin/nd-mcp
- With your actual nd-mcp path (stdio method only)
How to Use
Once configured, start Crush and it will automatically connect to your Netdata MCP servers:
# Start Crush
crush
# Ask infrastructure questions
What's the current CPU usage across all servers?
Show me any performance anomalies in the last hour
Which services are consuming the most resources?
Tool Permissions
Crush asks for permission before running tools by default. You can pre-approve certain Netdata tools:
{
"$schema": "https://charm.land/crush.json",
"permissions": {
"allowed_tools": [
"mcp_netdata_list_metrics",
"mcp_netdata_query_metrics",
"mcp_netdata_list_nodes",
"mcp_netdata_list_alerts"
]
}
}
⚠️ Warning: Use the
--yolo
flag to bypass all permission prompts, but be extremely careful with this feature.
Example Workflows
Performance Investigation:
Investigate why our application response times increased this afternoon using Netdata metrics
Resource Optimization:
Check memory usage patterns across all nodes and suggest optimization strategies
Alert Analysis:
Explain the current active alerts from Netdata and their potential impact
Anomaly Detection:
Find any anomalous metrics in the last 2 hours and explain what might be causing them
💡 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.
Troubleshooting
MCP Server Not Connecting
- Verify Netdata is accessible:
curl http://YOUR_NETDATA_IP:19999/api/v3/info
- Check the JSON syntax in your configuration file
- Ensure the MCP server is not disabled (
"disabled": false
)
Connection Timeouts
- Increase the
timeout
value in your configuration (default is 120 seconds) - Check network connectivity between Crush and Netdata
- Verify firewall rules allow access to port 19999
Limited Data Access
- Verify API key is included in the connection URL or headers
- Check that the Netdata agent is properly configured for MCP
- Ensure MCP is enabled in your Netdata build
Environment Variable Issues
- Crush uses
$(echo $VAR)
syntax, not$VAR
or$\{VAR}
- Ensure environment variables are exported before starting Crush
- Test with
echo $NETDATA_API_KEY
to verify the variable is set
Advanced Configuration
Multiple Environments with Different Transports
Configure different Netdata instances using different transport methods:
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"netdata-local": {
"type": "stdio",
"command": "/usr/sbin/nd-mcp",
"args": ["ws://localhost:19999/mcp"],
"timeout": 60
},
"netdata-parent": {
"type": "http",
"url": "https://parent.company.com:19999/mcp",
"headers": {
"Authorization": "Bearer $\{PARENT_API_KEY}"
},
"timeout": 180
},
"netdata-streaming": {
"type": "sse",
"url": "https://stream-parent.company.com:19999/mcp?transport=sse",
"headers": {
"Authorization": "Bearer $\{STREAM_API_KEY}"
},
"timeout": 300
}
}
}
ℹ️ Before switching between environments, export
ND_MCP_BEARER_TOKEN
with the matching key so the bridge authenticates without exposing credentials in the JSON file.
Debugging MCP Connections
Enable debug logging to troubleshoot MCP issues:
{
"$schema": "https://charm.land/crush.json",
"options": {
"debug": true
}
}
View logs:
# View recent logs
crush logs
# Follow logs in real-time
crush logs --follow
Documentation Links
Do you have any feedback for this page? If so, you can open a new issue on our netdata/learn repository.