# Datadog MCP Server

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that connects to the Datadog API, enabling natural-language investigation workflows through Claude Desktop, Claude Code, or any MCP client.

Scan logs for errors, identify problematic services, query metrics, explore monitors/dashboards/traces — all through conversation.

## Setup

```bash
npm install
npm run build
```

Requires three environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `DD_API_KEY` | Yes | — | **API Key** — identifies your Datadog organization. Found in Organization Settings → API Keys. |
| `DD_APP_KEY` | Yes | — | **Application Key** — tied to a specific user account and grants that user's read permissions. Create one in Organization Settings → Application Keys. |
| `DD_SITE` | No | `datadoghq.com` | Datadog site (e.g. `datadoghq.eu`, `us5.datadoghq.com`). |

## MCP Client Configuration

### Claude Code

```bash
claude mcp add datadog -- node /path/to/datadog/build/index.js
```

Then set `DD_API_KEY` and `DD_APP_KEY` in the environment where Claude Code runs.

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "datadog": {
      "command": "node",
      "args": ["/path/to/datadog/build/index.js"],
      "env": {
        "DD_API_KEY": "your-api-key",
        "DD_APP_KEY": "your-app-key"
      }
    }
  }
}
```

### MCP Inspector (for testing)

```bash
DD_API_KEY=xxx DD_APP_KEY=yyy npx @modelcontextprotocol/inspector build/index.js
```

## Tools

### Logs
| Tool | Description |
|---|---|
| `search_logs` | Search logs with structured filters (`service`, `env`, `status`, `host`) or raw Datadog query syntax. Supports cursor pagination. |

### Metrics
| Tool | Description |
|---|---|
| `query_metrics` | Query timeseries data (e.g. `avg:system.cpu.user{env:prod} by {host}`). Returns summary stats per series. |
| `list_metrics` | Search available metric names by prefix. |

### Monitors
| Tool | Description |
|---|---|
| `list_monitors` | List monitors filtered by name, tags, status, or type. |
| `get_monitor` | Get full monitor details including query, message, and thresholds. |
| `search_monitors` | Full-text search across monitor names, queries, and messages. |

### Traces / APM
| Tool | Description |
|---|---|
| `search_traces` | Search APM spans by service, operation, environment, status, or duration. |

### Hosts
| Tool | Description |
|---|---|
| `list_hosts` | List infrastructure hosts with CPU, load, and IOWait metrics. |
| `get_host_totals` | Get counts of active and up hosts. |

### Dashboards
| Tool | Description |
|---|---|
| `list_dashboards` | List dashboards with optional title search. |
| `get_dashboard` | Get dashboard details including all widgets and their queries. |

### Events
| Tool | Description |
|---|---|
| `list_events` | Search events (deploys, alerts, etc.) with cursor pagination. |

### Incidents
| Tool | Description |
|---|---|
| `list_incidents` | List incidents with optional search. |
| `get_incident` | Get incident details including severity, status, and timeline. |

## Time Parameters

All time parameters accept relative strings or ISO 8601:

| Format | Example | Meaning |
|---|---|---|
| Minutes | `15m` | 15 minutes ago |
| Hours | `4h` | 4 hours ago |
| Days | `7d` | 7 days ago |
| Weeks | `2w` | 2 weeks ago |
| Now | `now` | Current time |
| ISO 8601 | `2025-01-15T10:00:00Z` | Exact timestamp |

## Example Prompts

- "What errors have occurred in the last hour?"
- "Show me CPU usage for production hosts over the past day"
- "Which monitors are currently alerting?"
- "Search for traces with errors in the checkout service"
- "List recent deploy events"

## Development

```bash
npm run dev    # watch mode — recompiles on change
npm run build  # one-time build
npm start      # run the server
```

This server is **read-only** — no write or mutate operations are exposed, making it safe for production investigation.