# Datadog MCP Server

A comprehensive Model Context Protocol (MCP) server for Datadog integration, providing broad read/write access to Datadog APIs with modern async patterns. Built with the official Datadog Python SDK and MCP Python SDK.

## 🚀 Features

- 🔧 **Read/write operations** - Create, read, update across supported APIs
- ⚡ **Async operations** - Built with AsyncApiClient for optimal performance
- 🔄 **Automatic retries** - Rate limiting and error handling with exponential backoff
- 📊 **Comprehensive coverage** - 44 tools across all major Datadog APIs
- 💾 **Local caching** - Results stored as timestamped JSON files
- 🔒 **Type-safe** - Full type hints and Pydantic models
- 📈 **Built-in analysis** - Statistical analysis, trend detection, and data summarization
- 🛡️ **Security-first** - Environment-based credential management

## 📋 Prerequisites

- Python 3.8+
- Valid Datadog API and Application keys
- MCP-compatible client (VS Code, Cursor, Claude Desktop, etc.)

## Quick Start

```bash
# Install dependencies
pip install -r requirements.txt

# Set environment variables
export DATADOG_API_KEY="your_api_key"
export DATADOG_APP_KEY="your_app_key"
export DATADOG_SITE="datadoghq.com"  # Optional

# Run the server
python server.py
```

## MCP Client Integration

### VS Code with Continue

1. Install the Continue extension in VS Code
2. Add to your Continue config (`~/.continue/config.json`):

```json
{
  "mcpServers": {
    "datadog": {
      "command": "python",
      "args": ["/path/to/datadog-mcp-python/server.py"],
      "env": {
        "DATADOG_API_KEY": "your_api_key",
        "DATADOG_APP_KEY": "your_app_key"
      }
    }
  }
}
```

### Cursor

1. Open Cursor settings
2. Add MCP server configuration:

```json
{
  "mcp.servers": {
    "datadog": {
      "command": "python",
      "args": ["/path/to/datadog-mcp-python/server.py"],
      "env": {
        "DATADOG_API_KEY": "your_api_key",
        "DATADOG_APP_KEY": "your_app_key"
      }
    }
  }
}
```

### Amazon Q Developer

1. Configure in your Q Developer settings:

```json
{
  "mcpServers": {
    "datadog-mcp": {
      "command": "python3",
      "args": ["/path/to/datadog-mcp-python/server.py"],
      "env": {
        "DATADOG_API_KEY": "your_api_key",
        "DATADOG_APP_KEY": "your_app_key",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Claude Desktop

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

```json
{
  "mcpServers": {
    "datadog": {
      "command": "python",
      "args": ["/path/to/datadog-mcp-python/server.py"],
      "env": {
        "DATADOG_API_KEY": "your_api_key",
        "DATADOG_APP_KEY": "your_app_key"
      }
    }
  }
}
```

### Gemini CLI

1. Install Gemini CLI with MCP support
2. Configure the server:

```bash
gemini mcp add datadog python /path/to/datadog-mcp-python/server.py \
  --env DATADOG_API_KEY=your_api_key \
  --env DATADOG_APP_KEY=your_app_key
```

### Generic MCP Client

For any MCP-compatible client, use these connection details:

- **Transport**: stdio
- **Command**: `python server.py`
- **Working Directory**: `/path/to/datadog-mcp-python/`
- **Environment Variables**: `DATADOG_API_KEY`, `DATADOG_APP_KEY`

## Available Tools (44 Total)

### Metrics & Monitoring (9 tools)
- `validate_api_key` - Test API credentials
- `get_metrics` - Query time series data
- `search_metrics` - Find metrics by pattern
- `get_metric_metadata` - Get metric metadata
- `get_monitors` - List monitoring alerts
- `get_monitor` - Get specific monitor details
- `create_monitor` - Create new monitoring alerts
- `update_monitor` - Update existing monitors
- `delete_monitor` - Delete monitors

### Dashboards & Visualization (5 tools)
- `get_dashboards` - List all dashboards
- `get_dashboard` - Get dashboard details
- `create_dashboard` - Create new dashboards
- `update_dashboard` - Update existing dashboards
- `delete_dashboard` - Delete dashboards

### Logs & Events (4 tools)
- `search_logs` - Search log entries
- `get_events` - Get system events
- `get_event` - Get a specific event
- `search_events` - Search events (v2)

### Infrastructure & Tags (5 tools)
- `get_infrastructure` - Get host information
- `get_service_map` - Get service dependencies
- `get_tags` - Get host tags
- `get_downtimes` - Get scheduled downtimes
- `create_downtime` - Create scheduled downtimes

### Testing & Applications (2 tools)
- `get_synthetics_tests` - Get synthetic tests
- `get_rum_applications` - Get RUM applications

### Security & Incidents (11 tools)
- `get_security_rules` - Get security monitoring rules
- `get_incidents` - Get incident data (with pagination)
- `get_slos` - Get Service Level Objectives
- `get_notebooks` - Get Datadog notebooks
- `create_notebook` - Create Datadog notebooks
- `update_notebook` - Update Datadog notebooks
- `search_error_tracking_issues` - Search error tracking issues
- `get_error_tracking_issue` - Get error tracking issue details
- `update_error_tracking_issue_state` - Update error tracking issue state
- `update_error_tracking_issue_assignee` - Update error tracking assignee
- `remove_error_tracking_issue_assignee` - Remove error tracking assignee

### Teams & Users (2 tools)
- `get_teams` - Get teams
- `get_users` - Get users

### Utilities (2 tools)
- `analyze_data` - Analyze cached data
- `cleanup_cache` - Clean old cache files

## Usage Examples

Once connected to an MCP client, you can use natural language to interact with Datadog:

### Monitoring Examples
- "Show me all monitors that are currently alerting"
- "Create a monitor for high CPU usage above 80%"
- "Get metrics for system.cpu.user over the last hour"
- "Search for all memory-related metrics"

### Dashboard Examples
- "List all my dashboards"
- "Create a new dashboard for system monitoring"
- "Show me the widgets in my main dashboard"

### Infrastructure Examples
- "Show me all hosts and their status"
- "Get the service map for my application"
- "List all tags for production hosts"

### Incident Management
- "Show me all active incidents"
- "Get the latest security monitoring rules"
- "List all SLOs and their current status"

## Configuration

The server uses the latest Datadog API client with:
- AsyncApiClient for non-blocking operations
- Automatic retry on rate limits (429 errors)
- 3 retry attempts with exponential backoff
- Unstable operations enabled for pagination

## 🏗️ Architecture

### Core Components
- **DatadogMCPServer**: Main server class with API client management
- **DatadogConfig**: Pydantic model for configuration validation
- **Tool Handlers**: Individual async functions for each API endpoint
- **Data Storage**: Automatic JSON file caching with timestamps
- **Analysis Engine**: Built-in data analysis capabilities

### Data Flow
1. **Request**: MCP client calls tool with parameters
2. **API Call**: Server makes authenticated request to Datadog API
3. **Storage**: Response data is cached to local JSON file
4. **Analysis**: Optional built-in analysis of the data
5. **Response**: Summary and file path returned to client

## 📈 Performance

### Async Implementation
- All API calls are asynchronous
- Non-blocking file I/O operations
- Efficient memory usage for large datasets

### Rate Limiting
- Respects Datadog API rate limits
- Automatic retry logic with exponential backoff
- Efficient batching for bulk operations

## Example Code Usage

```python
# Create a monitor
create_monitor(
    name="High CPU Usage",
    monitor_type="metric alert", 
    query="avg(last_5m):avg:system.cpu.user{*} > 0.8",
    message="CPU usage is high @slack-alerts"
)

# Create a dashboard
create_dashboard(
    title="System Overview",
    layout_type="ordered",
    widgets=[{
        "definition": {
            "type": "timeseries",
            "requests": [{"q": "avg:system.cpu.user{*}"}]
        }
    }]
)

# Schedule downtime
create_downtime(
    scope=["host:web-server-01"],
    start=1640995200,
    end=1640998800,
    message="Scheduled maintenance"
)
```

## Security & Features

- **Read/write operations** - Create, read, update support
- **Selective mutations** - Write tools only where supported
- **Local data caching** - All results stored locally as JSON files
- **Error handling** - Comprehensive exception management
- **Pagination support** - Handle large datasets efficiently
- **Type safety** - Full type hints throughout
- **Rate limiting** - Automatic retry on API limits

## Development

### Setup
```bash
# Install development dependencies
pip install -r requirements.txt
pip install pytest pytest-cov black flake8 mypy

# Format code
black server.py
flake8 server.py --max-line-length=88

# Run tests
cd tests && python -m pytest --cov=../server
```

### Adding New Tools
1. Add new method to `DatadogMCPServer` class
2. Decorate with `@self.mcp.tool()`
3. Implement proper error handling and data storage
4. Add tests and update documentation

## Troubleshooting

### Common Issues

1. **Authentication Error**: Verify your `DATADOG_API_KEY` and `DATADOG_APP_KEY` are correct
2. **Connection Issues**: Ensure the server is running and accessible
3. **Permission Errors**: Check that your API keys have the necessary permissions
4. **Rate Limiting**: The server automatically handles rate limits with retries

### Debug Mode

Enable debug logging by setting:
```bash
export DATADOG_DEBUG=true
```

## License

MIT License - see LICENSE file for details.