# 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

1. **Crush installed** - Available via npm, Homebrew, or direct download from [GitHub](https://github.com/charmbracelet/crush)
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).
   - **v2.6.0 - v2.7.1**: Only WebSocket transport available, requires `nd-mcp` bridge
   - **v2.7.2+**: Direct HTTP/SSE support available (recommended)
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+.
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)

> Export `ND_MCP_BEARER_TOKEN` with your MCP key before launching Crush so credentials never appear in command-line arguments or config files:
> ```bash
> export ND_MCP_BEARER_TOKEN="$(cat /var/lib/netdata/mcp_dev_preview_api_key)"
> ```

## Installation

Install Crush using one of these methods:

```bash
# 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:
1. `.crush.json` (project-specific)
2. `crush.json` (project-specific)
3. `~/.config/crush/crush.json` (global)

### Netdata Cloud MCP

Connect to your entire Netdata Cloud infrastructure
through a single endpoint — no local setup, bridges,
or firewall changes needed.

**Prerequisites:**

- Netdata Cloud account with Business plan
- Nodes claimed to Netdata Cloud
- API token with `scope:mcp`
  ([create one](/docs/netdata-cloud/authentication-and-authorization/api-tokens.md))

```json
{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "netdata-cloud": {
      "type": "http",
      "url": "https://app.netdata.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NETDATA_CLOUD_API_TOKEN"
      },
      "timeout": 120,
      "disabled": false
    }
  }
}
```

Replace `YOUR_NETDATA_CLOUD_API_TOKEN` with your
Netdata Cloud API token (must have `scope:mcp`).
For more details, see
[Netdata Cloud MCP](/docs/netdata-ai/mcp/README.md#netdata-cloud-mcp).

### Local Agent or Parent

The following methods connect directly to a Netdata Agent or Parent on your network.

#### Method 1: Direct HTTP Connection (Recommended for v2.7.2+)

Connect directly to Netdata's HTTP endpoint without needing the nd-mcp bridge:

```json
{
  "$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:

```json
{
  "$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:

```json
{
  "$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:

```json
{
  "$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 mcp-remote (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](/docs/netdata-ai/mcp/README.md#using-mcp-remote-client).

```json
{
  "$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:

```json
{
  "$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:

```json
{
  "$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/Parent
- `NETDATA_MCP_API_KEY` - Your [Netdata MCP API key](/docs/netdata-ai/mcp/README.md#finding-your-api-key)
- `/usr/sbin/nd-mcp` - With your [actual nd-mcp path](/docs/netdata-ai/mcp/README.md#finding-the-nd-mcp-bridge) (stdio method only)

## How to Use

Once configured, start Crush and it will automatically connect to your Netdata MCP servers:

```bash
# 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:

```json
{
  "$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](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md).

## 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:

```json
{
  "$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:

```json
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": true
  }
}
```

View logs:
```bash
# View recent logs
crush logs

# Follow logs in real-time
crush logs --follow
```

## Documentation Links

- [Crush GitHub Repository](https://github.com/charmbracelet/crush)
- [Crush Configuration Schema](https://charm.land/crush.json)
- [Charmbracelet Documentation](https://charm.sh)
- [Netdata MCP Setup](/docs/netdata-ai/mcp/README.md)
- [AI DevOps Best Practices](/docs/netdata-ai/mcp/mcp-clients/ai-devops-copilot.md)
