MCP server providing AI assistants with full Datadog observability access. Features grep-like log search, APM trace filtering with duration/status/error queries, smart sampling modes for token efficiency, and cross-correlation between logs, traces, and metrics. Use environment variables instead of container args: When running with --transport=http: - POST /mcp — MCP protocol endpoint - GET /mcp —
Add this skill
npx mdskills install TANTIOPE/datadog-mcp-serverComprehensive Datadog integration with extensive tool coverage, clear configuration, and thoughtful token optimization features
1# Datadog MCP Server23[](https://sonarcloud.io/summary/new_code?id=TANTIOPE_datadog-mcp-server)4[](https://github.com/tantiope/datadog-mcp-server/actions/workflows/release.yml)5[](https://www.npmjs.com/package/datadog-mcp)6[](https://opensource.org/licenses/Apache-2.0)7[](https://sonarcloud.io/summary/new_code?id=TANTIOPE_datadog-mcp-server)89> **DISCLAIMER**: This is a community-maintained project and is not officially affiliated with, endorsed by, or supported by Datadog, Inc. This MCP server utilizes the Datadog API but is developed independently.1011MCP server providing AI assistants with full Datadog observability access. Features grep-like log search, APM trace filtering with duration/status/error queries, smart sampling modes for token efficiency, and cross-correlation between logs, traces, and metrics.1213## Configuration1415### Required Environment Variables1617```bash18DD_API_KEY=your-api-key19DD_APP_KEY=your-app-key20```2122### Optional Environment Variables2324```bash25DD_SITE=datadoghq.com # Default. Use datadoghq.eu for EU, etc.2627# Limit defaults (fallbacks when AI doesn't specify)28MCP_DEFAULT_LIMIT=50 # General tools default limit29MCP_DEFAULT_LOG_LINES=200 # Logs tool default limit30MCP_DEFAULT_METRIC_POINTS=1000 # Metrics timeseries data points31MCP_DEFAULT_TIME_RANGE=24 # Default time range in hours32```3334### Optional Flags3536```bash37--site=datadoghq.com # Datadog site (overrides DD_SITE)38--transport=stdio|http # Transport mode (default: stdio)39--port=3000 # HTTP port when using http transport40--host=0.0.0.0 # HTTP host when using http transport41--read-only # Block all write operations42--disable-tools=synthetics,rum,security # Comma-separated list of tools to disable43```4445## Usage4647### Claude Desktop / VS Code / Cursor4849```json50{51 "mcpServers": {52 "datadog": {53 "command": "npx",54 "args": ["-y", "datadog-mcp"],55 "env": {56 "DD_API_KEY": "your-api-key",57 "DD_APP_KEY": "your-app-key",58 "DD_SITE": "datadoghq.com"59 }60 }61 }62}63```6465### Docker6667```json68{69 "mcpServers": {70 "datadog": {71 "command": "docker",72 "args": [73 "run", "-i", "--rm",74 "-e", "DD_API_KEY",75 "-e", "DD_APP_KEY",76 "-e", "DD_SITE",77 "ghcr.io/tantiope/datadog-mcp"78 ],79 "env": {80 "DD_API_KEY": "your-api-key",81 "DD_APP_KEY": "your-app-key",82 "DD_SITE": "datadoghq.com"83 }84 }85 }86}87```8889### Kubernetes9091**Use environment variables instead of container args:**9293```yaml94env:95 - name: DD_API_KEY96 value: "your-api-key"97 - name: DD_APP_KEY98 value: "your-app-key"99 - name: MCP_TRANSPORT100 value: "http"101 - name: MCP_PORT102 value: "3000"103 - name: MCP_HOST104 value: "0.0.0.0"105```106107> **Note:** Kubernetes `args:` replaces the entire Dockerfile CMD, causing Node.js to receive the flags instead of your application. Environment variables avoid this issue.108109### HTTP Transport110111When running with `--transport=http`:112113- `POST /mcp` — MCP protocol endpoint114- `GET /mcp` — SSE stream for responses115- `DELETE /mcp` — Close session116- `GET /health` — Health check117118## Tools119120| Tool | Action | Category | Description | Required Scopes |121|------|--------|----------|-------------|-----------------|122| `monitors` | list | Alerting | List monitors with optional filters | `monitors_read` |123| `monitors` | get | Alerting | Get monitor by ID | `monitors_read` |124| `monitors` | search | Alerting | Search monitors by query | `monitors_read` |125| `monitors` | create | Alerting | Create a new monitor | `monitors_write` |126| `monitors` | update | Alerting | Update an existing monitor | `monitors_write` |127| `monitors` | delete | Alerting | Delete a monitor | `monitors_write` |128| `monitors` | mute | Alerting | Mute a monitor | `monitors_write` |129| `monitors` | unmute | Alerting | Unmute a monitor | `monitors_write` |130| `monitors` | top | Alerting | Top N monitors by alert frequency with real monitor names and context breakdown. Groups without context tags are included as "no_context" | `monitors_read` |131| `dashboards` | list | Visualization | List all dashboards | `dashboards_read` |132| `dashboards` | get | Visualization | Get dashboard by ID | `dashboards_read` |133| `dashboards` | create | Visualization | Create a new dashboard | `dashboards_write` |134| `dashboards` | update | Visualization | Update a dashboard | `dashboards_write` |135| `dashboards` | delete | Visualization | Delete a dashboard | `dashboards_write` |136| `logs` | search | Logs | Search logs with query syntax and filters | `logs_read_data`, `logs_read_index_data` |137| `logs` | aggregate | Logs | Aggregate log data with groupBy | `logs_read_data` |138| `metrics` | query | Metrics | Query timeseries data | `metrics_read`, `timeseries_query` |139| `metrics` | search | Metrics | Search for metrics by name | `metrics_read` |140| `metrics` | list | Metrics | List active metrics | `metrics_read` |141| `metrics` | metadata | Metrics | Get metric metadata | `metrics_read` |142| `traces` | search | APM | Search spans with filters | `apm_read` |143| `traces` | aggregate | APM | Aggregate trace data | `apm_read` |144| `traces` | services | APM | List APM services | `apm_service_catalog_read` |145| `events` | list | Events | List events | `events_read` |146| `events` | get | Events | Get event by ID | `events_read` |147| `events` | create | Events | Create an event | `events_read` |148| `events` | search | Events | Search events with v2 API and cursor pagination | `events_read` |149| `events` | aggregate | Events | Client-side aggregation by monitor_name, source, etc. | `events_read` |150| `events` | top | Events | Top N event groups by count with generic groupBy support (deployments, configs, alerts, etc.). Groups without context tags are included as "no_context" | `events_read` |151| `events` | timeseries | Events | Time-bucketed alert trends (hourly/daily counts) | `events_read` |152| `events` | incidents | Events | Deduplicate alerts into incidents with Trigger/Recover pairing | `events_read` |153| `incidents` | list | Incidents | List incidents | `incident_read` |154| `incidents` | get | Incidents | Get incident by ID | `incident_read` |155| `incidents` | search | Incidents | Search incidents | `incident_read` |156| `incidents` | create | Incidents | Create an incident | `incident_write` |157| `incidents` | update | Incidents | Update an incident | `incident_write` |158| `incidents` | delete | Incidents | Delete an incident | `incident_write` |159| `slos` | list | SLOs | List SLOs | `slos_read` |160| `slos` | get | SLOs | Get SLO by ID | `slos_read` |161| `slos` | create | SLOs | Create an SLO | `slos_write` |162| `slos` | update | SLOs | Update an SLO | `slos_write` |163| `slos` | delete | SLOs | Delete an SLO | `slos_write` |164| `slos` | history | SLOs | Get SLO history | `slos_read` |165| `synthetics` | list | Synthetics | List synthetic tests | `synthetics_read` |166| `synthetics` | get | Synthetics | Get test by public ID | `synthetics_read` |167| `synthetics` | create | Synthetics | Create a test | `synthetics_write` |168| `synthetics` | update | Synthetics | Update a test | `synthetics_write` |169| `synthetics` | delete | Synthetics | Delete a test | `synthetics_write` |170| `synthetics` | trigger | Synthetics | Trigger a test run | `synthetics_write` |171| `synthetics` | results | Synthetics | Get test results | `synthetics_read` |172| `downtimes` | list | Downtimes | List downtimes | `monitors_downtime` |173| `downtimes` | get | Downtimes | Get downtime by ID | `monitors_downtime` |174| `downtimes` | create | Downtimes | Create a downtime | `monitors_downtime` |175| `downtimes` | update | Downtimes | Update a downtime | `monitors_downtime` |176| `downtimes` | cancel | Downtimes | Cancel a downtime | `monitors_downtime` |177| `downtimes` | listByMonitor | Downtimes | List downtimes for a monitor | `monitors_downtime` |178| `hosts` | list | Infrastructure | List hosts | `hosts_read` |179| `hosts` | totals | Infrastructure | Get host totals | `hosts_read` |180| `hosts` | mute | Infrastructure | Mute a host | `hosts_read` |181| `hosts` | unmute | Infrastructure | Unmute a host | `hosts_read` |182| `rum` | applications | RUM | List RUM applications | `rum_read` |183| `rum` | events | RUM | Search RUM events | `rum_read` |184| `rum` | aggregate | RUM | Aggregate RUM data | `rum_read` |185| `rum` | performance | RUM | Get Core Web Vitals (LCP, FCP, CLS, FID, INP) | `rum_read` |186| `rum` | waterfall | RUM | Get session timeline with resources/actions/errors | `rum_read` |187| `security` | rules | Security | List security rules | `security_monitoring_rules_read` |188| `security` | signals | Security | Search security signals | `security_monitoring_signals_read` |189| `security` | findings | Security | List security findings | `security_monitoring_findings_read` |190| `notebooks` | list | Notebooks | List notebooks | `notebooks_read` |191| `notebooks` | get | Notebooks | Get notebook by ID | `notebooks_read` |192| `notebooks` | create | Notebooks | Create a notebook | `notebooks_write` |193| `notebooks` | update | Notebooks | Update a notebook | `notebooks_write` |194| `notebooks` | delete | Notebooks | Delete a notebook | `notebooks_write` |195| `users` | list | Admin | List users | `user_access_read` |196| `users` | get | Admin | Get user by ID | `user_access_read` |197| `teams` | list | Admin | List teams | `teams_read` |198| `teams` | get | Admin | Get team by ID | `teams_read` |199| `teams` | members | Admin | List team members | `teams_read` |200| `tags` | list | Infrastructure | List all tags | `hosts_read` |201| `tags` | get | Infrastructure | Get tags for a host | `hosts_read` |202| `tags` | add | Infrastructure | Add tags to a host | `hosts_read` |203| `tags` | update | Infrastructure | Update host tags | `hosts_read` |204| `tags` | delete | Infrastructure | Delete host tags | `hosts_read` |205| `usage` | summary | Billing | Usage summary | `usage_read` |206| `usage` | hosts | Billing | Host usage | `usage_read` |207| `usage` | logs | Billing | Log usage | `usage_read` |208| `usage` | custom_metrics | Billing | Custom metrics usage | `usage_read` |209| `usage` | indexed_spans | Billing | Indexed spans usage | `usage_read` |210| `usage` | ingested_spans | Billing | Ingested spans usage | `usage_read` |211| `auth` | validate | Auth | Test API and App key validity | — |212213## Token Efficiency214215### Limit Control216217AI assistants have full control over query limits. The environment variables set what value is used when the AI doesn't specify a limit. They do NOT cap what the AI can request.218219| Tool | Default | Parameter | Description |220|------|---------|-----------|-------------|221| Logs | 200 | `limit` | Log lines to return |222| Metrics (timeseries) | 1000 | `pointLimit` | Data points per series (controls resolution) |223| General tools | 50 | `limit` | Results to return |224225Defaults can be configured via `MCP_DEFAULT_*` environment variables:226227```json228{229 "mcpServers": {230 "datadog": {231 "command": "npx",232 "args": ["-y", "datadog-mcp"],233 "env": {234 "DD_API_KEY": "your-api-key",235 "DD_APP_KEY": "your-app-key",236 "MCP_DEFAULT_LIMIT": "50", // General fallback for most tools237 "MCP_DEFAULT_LOG_LINES": "200", // Logs search only238 "MCP_DEFAULT_METRIC_POINTS": "1000", // Metrics query timeseries only239 "MCP_DEFAULT_TIME_RANGE": "24" // Default time range in hours240 }241 }242 }243}244```245246### Compact Mode (Logs)247248Use `compact: true` when searching logs to reduce token usage. Strips custom attributes and keeps only essential fields:249250```251logs({ action: "search", status: "error", compact: true })252```253254Returns: `id`, `timestamp`, `service`, `status`, `message` (truncated), `traceId`, `spanId`, `error`255256### Sampling Modes (Logs)257258Control how logs are sampled with the `sample` parameter:259260| Mode | Description | Use Case |261|------|-------------|----------|262| `first` | Chronological order (default) | Timeline analysis, specific events |263| `spread` | Evenly distributed across time range | See patterns over time |264| `diverse` | Deduplicated by message pattern | Error investigation (distinct error types) |265266Example - find distinct error patterns:267```268logs({ action: "search", status: "error", sample: "diverse", limit: 25 })269```270271The `diverse` mode normalizes messages (strips UUIDs, timestamps, IPs, numbers) to identify unique error patterns instead of returning duplicates.272273## Events Aggregation274275### Top Monitors Report (Monitor-Specific)276277**Use `monitors` tool for monitor alerts with real monitor names:**278279```280monitors({ action: "top", from: "7d", limit: 10 })281```282283Returns monitors with **real names** (including {{template.vars}}) from monitors API:284```json285{286 "top": [287 {288 "rank": 1,289 "monitor_id": 67860480,290 "name": "High number of ready messages on {{queue.name}}",291 "message": "Queue {{queue.name}} has {{value}} ready messages",292 "total_count": 50,293 "by_context": [294 {"context": "queue:email-notifications", "count": 30},295 {"context": "queue:payment-processing", "count": 20}296 ]297 },298 {299 "rank": 2,300 "monitor_id": 134611486,301 "name": "Nginx some requests on errors (HTTP 5XX) on {{ingress.name}}",302 "message": "Nginx request on ingress {{ingress.name}} contains some errors (HTTP 5XX)",303 "total_count": 42,304 "by_context": [305 {"context": "ingress:api-gateway", "count": 29},306 {"context": "ingress:admin-panel", "count": 13}307 ]308 }309 ]310}311```312313### Top Events Report (Generic)314315**Use `events` tool for any event type** (deployments, configs, custom events):316317```318events({ action: "top", from: "7d", limit: 10, groupBy: ["service"] })319```320321Returns event groups by custom fields:322```json323{324 "top": [325 {326 "rank": 1,327 "service": "api-server",328 "message": "Deployment completed",329 "total_count": 30,330 "by_context": [331 {"context": "env:prod", "count": 20},332 {"context": "env:staging", "count": 10}333 ]334 }335 ]336}337```338339**Key Differences:**340- `monitors top`: Fetches real monitor names from monitors API (slower, monitor-specific)341- `events top`: Fast generic grouping, returns event message text (any event type)342343Context tags are auto-extracted: `queue:`, `service:`, `ingress:`, `pod_name:`, `kube_namespace:`, `kube_container_name:`344345### Tag Discovery346347Discover available tag prefixes in your alert data:348349```350events({ action: "discover", from: "7d", tags: ["source:alert"] })351```352353Returns: `{tagPrefixes: ["queue", "service", "ingress", "pod_name", "monitor", "priority"], sampleSize: 150}`354355### Custom Aggregation356357For custom grouping patterns, use `aggregate`:358359```360events({361 action: "aggregate",362 from: "7d",363 tags: ["source:alert"],364 groupBy: ["monitor_name", "priority"]365})366```367368Supported groupBy fields: `monitor_name`, `priority`, `alert_type`, `source`, `status`, `host`, or any tag prefix369370The aggregation uses v2 API with cursor pagination to stream through events efficiently (up to 10k events).371372## Alert Trends (Timeseries)373374Visualize alert patterns over time with time-bucketed aggregation:375376```377events({ action: "timeseries", from: "7d", interval: "1d" })378```379380Returns hourly/daily alert counts grouped by monitor:381```json382{383 "timeseries": [384 { "timestamp": "2024-01-15T00:00:00Z", "counts": { "High CPU": 5, "Low Disk": 2 }, "total": 7 },385 { "timestamp": "2024-01-16T00:00:00Z", "counts": { "High CPU": 3 }, "total": 3 }386 ]387}388```389390| Interval | Use Case |391|----------|----------|392| `1h` | Recent incident analysis (default) |393| `4h` | Daily patterns |394| `1d` | Weekly trends |395396Combine with `groupBy` to see trends per monitor, source, or priority.397398## Incident Deduplication399400Consolidate noisy alert floods into logical incidents:401402```403events({ action: "incidents", from: "24h", dedupeWindow: "5m" })404```405406Groups repeated triggers within the dedupe window and pairs with recovery events:407```json408{409 "incidents": [410 {411 "monitorName": "High CPU Usage",412 "firstTrigger": "2024-01-15T10:00:00Z",413 "lastTrigger": "2024-01-15T10:15:00Z",414 "triggerCount": 4,415 "recovered": true,416 "recoveredAt": "2024-01-15T10:30:00Z",417 "duration": "30m"418 }419 ],420 "meta": { "totalIncidents": 15, "recoveredCount": 12, "activeCount": 3 }421}422```423424| Dedupe Window | Use Case |425|---------------|----------|426| `5m` | Flapping detection (default) |427| `15m` | Alert storm consolidation |428| `1h` | Incident grouping |429430## Monitor Enrichment431432Add monitor metadata to search results for deeper context:433434```435events({ action: "search", tags: ["source:alert"], from: "1h", enrich: true })436```437438Returns events with monitor details (type, thresholds, tags):439```json440{441 "events": [{442 "id": "...",443 "title": "[Triggered on {host:prod-1}] High CPU Usage",444 "monitorMetadata": {445 "id": 12345,446 "type": "metric alert",447 "message": "CPU is above threshold",448 "tags": ["team:platform", "env:prod"],449 "options": { "thresholds": { "critical": 90 } }450 }451 }]452}453```454455Note: Enrichment adds latency (fetches monitor list). Use for detailed investigation, not bulk analysis.456457## Cross-Correlation458459### Logs → Traces → Metrics4604611. **Find errors in logs**: `logs({ action: "search", status: "error", sample: "diverse" })`4622. **Extract trace_id** from log attributes (`dd.trace_id`)4633. **Get full trace**: `traces({ action: "search", query: "trace_id:<id>" })`4644. **Query APM metrics** (avg): `metrics({ action: "query", query: "avg:trace.express.request.duration{service:my-service}" })`4655. **Query APM latency percentiles** (p95): `metrics({ action: "query", query: "p95:trace.express.request{service:my-service}" })` — note: use root metric without `.duration` suffix for percentiles466467## Deep Links468469All query responses include a `datadog_url` field that links directly to the Datadog UI, allowing AI assistants to provide evidence links back to the source data.470471### Example Response472473```json474{475 "logs": [...],476 "meta": {477 "count": 25,478 "query": "service:api status:error",479 "from": "2024-01-15T10:00:00Z",480 "to": "2024-01-15T11:00:00Z",481 "datadog_url": "https://app.datadoghq.com/logs?query=service%3Aapi%20status%3Aerror&from_ts=1705312800000&to_ts=1705316400000"482 }483}484```485486### Supported Tools487488| Tool | URL Type |489|------|----------|490| `logs` | Logs Explorer with query and time range |491| `metrics` | Metrics Explorer with query and time range |492| `traces` | APM Traces with query and time range |493| `events` | Event Explorer with query and time range |494| `monitors` | Monitor detail page (get) or Manage Monitors (list/search) |495| `rum` | RUM Explorer or Session Replay |496497### Multi-Region Support498499URLs are automatically generated for your configured Datadog site:500501| Site | App URL |502|------|---------|503| `datadoghq.com` (default) | `https://app.datadoghq.com` |504| `datadoghq.eu` | `https://app.datadoghq.eu` |505| `us3.datadoghq.com` | `https://us3.datadoghq.com` |506| `us5.datadoghq.com` | `https://us5.datadoghq.com` |507| `ap1.datadoghq.com` | `https://ap1.datadoghq.com` |508| `ddog-gov.com` | `https://app.ddog-gov.com` |509510Configure your site via the `DD_SITE` environment variable or `--site` flag.511512## Contributing513514Contributions are welcome! Feel free to open an issue or a pull request if you have any suggestions, bug reports, or improvements to propose.515516## License517518This project is licensed under the [Apache License, Version 2.0](LICENSE).519
Full transparency — inspect the skill content before installing.