MCP Prometheus

A comprehensive Model Context Protocol (MCP) server for Prometheus, written in Go.

This provides complete access to your Prometheus metrics, queries, and system information through standardized MCP interfaces, allowing AI assistants to execute PromQL queries, discover metrics, explore labels, and analyze your monitoring infrastructure.

Features

🔍 Query Execution

• Instant queries with optional timestamp and enhanced parameters
• Range queries with time bounds, step intervals, and performance options
• Query optimization with timeout, limit, and stats parameters
• Result truncation with intelligent user guidance for large datasets

📊 Metrics Discovery

• List all available metrics with filtering and time-based selection
• Get detailed metadata for specific metrics
• Metric exploration with enhanced filtering options

🏷️ Label & Series Discovery

• List all label names with filtering and limits
• Get label values for specific labels with advanced filtering
• Find series by label matchers with time bounds
• Advanced label matching with complex selectors

🎯 Target & System Information

• Scrape target information and health status
• Build information and version details
• Runtime information and system status
• Configuration and flags inspection
• TSDB statistics and cardinality information

🚨 Alerting & Rules

• Active alerts monitoring
• AlertManager discovery and status
• Recording and alerting rules inspection

🔬 Advanced Features

• Exemplar queries for trace correlation
• Target metadata exploration
• Multi-tenant support with dynamic organization IDs
• Dynamic client configuration per-query

🔐 Authentication & Transport

• Multiple authentication methods (Basic, Bearer token)
• Multi-tenant organization headers (Cortex, Mimir, Thanos)
• Multiple transport protocols (stdio, SSE, HTTP)
• Cross-platform binary distribution

Installation

Pre-built Binaries

Download the latest binary for your platform from the releases page.

From Source

git clone https://github.com/giantswarm/mcp-prometheus.git
cd mcp-prometheus
go build -o mcp-prometheus

Configuration

Configure the MCP server through environment variables (all optional):

# Optional: Default Prometheus server configuration
export PROMETHEUS_URL=http://your-prometheus-server:9090

# Optional: Authentication credentials (choose one)
# For basic auth
export PROMETHEUS_USERNAME=your_username
export PROMETHEUS_PASSWORD=your_password

# For bearer token auth  
export PROMETHEUS_TOKEN=your_token

# Optional: Default organization ID for multi-tenant setups
export PROMETHEUS_ORGID=your_organization_id

Dynamic Configuration: All MCP tools support prometheus_url and org_id parameters for per-query configuration, allowing you to query multiple Prometheus instances and organizations dynamically.

Usage

Command Line

Start the server with stdio transport (default):

./mcp-prometheus

Start with HTTP transport for web-based clients:

./mcp-prometheus serve --transport sse --http-addr :8080

MCP Client Configuration

Add the server configuration to your MCP client. For example, with Claude Desktop:

{
  "mcpServers": {
    "prometheus": {
      "command": "/path/to/mcp-prometheus",
      "args": ["serve"],
      "env": {
        "PROMETHEUS_URL": "http://your-prometheus-server:9090",
        "PROMETHEUS_ORGID": "your-default-org"
      }
    }
  }
}

Available Tools

🔍 Query Execution Tools

📊 Metrics Discovery Tools

🏷️ Label & Series Discovery Tools

🎯 Target & System Information Tools

🚨 Alerting & Rules Tools

🔬 Advanced Tools

🔧 Enhanced Parameters

Connection Parameters (available on all tools):

• prometheus_url: Prometheus server URL (e.g., 'http://localhost:9090')
• org_id: Organization ID for multi-tenant setups (e.g., 'tenant-123')

Query Enhancement Parameters:

• timeout: Query timeout (e.g., '30s', '1m', '5m')
• limit: Maximum number of returned entries
• stats: Include query statistics ('all')
• lookback_delta: Query lookback delta (e.g., '5m')
• unlimited: Set to 'true' for unlimited output (WARNING: may impact performance)

Time Filtering Parameters:

• start_time, end_time: RFC3339 timestamps for filtering
• matches: Array of label matchers (e.g., ['{job="prometheus"}', '{__name__=~"http_.*"}'])

Example Usage

Basic Query Execution

{
  "query": "up",
  "prometheus_url": "http://prometheus:9090",
  "org_id": "production"
}

Enhanced Query with Performance Options

{
  "query": "rate(http_requests_total[5m])",
  "prometheus_url": "http://prometheus:9090", 
  "timeout": "30s",
  "limit": "100",
  "stats": "all"
}

Range Query with Time Bounds

{
  "query": "cpu_usage_percent",
  "start": "2025-01-27T00:00:00Z",
  "end": "2025-01-27T01:00:00Z",
  "step": "1m",
  "prometheus_url": "http://prometheus:9090"
}

Label Discovery with Filtering

{
  "prometheus_url": "http://prometheus:9090",
  "matches": ["up{job=\"kubernetes-nodes\"}"],
  "limit": "20"
}

Series Discovery

{
  "matches": ["{__name__=~\"http_.*\", job=\"api-server\"}"],
  "prometheus_url": "http://prometheus:9090",
  "start_time": "2025-01-27T00:00:00Z",
  "limit": "50"
}

Multi-tenant Query

{
  "query": "container_memory_usage_bytes",
  "prometheus_url": "http://cortex-gateway:8080/prometheus",
  "org_id": "team-platform"
}

Query Result Optimization

The MCP server includes intelligent query result handling:

• Automatic truncation for results > 50k characters
• User guidance for query optimization when results are large
• Performance tips including aggregation functions and filtering
• Unlimited output option with performance warnings

Example truncation message:

⚠️  RESULT TRUNCATED: The query returned a very large result (>50k characters).

💡 To optimize your query and get less output, consider:
   • Adding more specific label filters: {app="specific-app", namespace="specific-ns"}
   • Using aggregation functions: sum(), avg(), count(), etc.
   • Using topk() or bottomk() to get only top/bottom N results

🔧 To get the full untruncated result, add "unlimited": "true" to your query parameters.

Transport Options

The server supports multiple transport protocols:

stdio (Default)

./mcp-prometheus serve --transport stdio

SSE (Server-Sent Events)

./mcp-prometheus serve --transport sse --http-addr :8080

Streamable HTTP

./mcp-prometheus serve --transport streamable-http --http-addr :8080

Development

Architecture

The server follows a modern, DRY architecture:

• Modular tool registration with parameter reuse
• Dynamic client creation for multi-instance support
• Centralized error handling and parameter validation
• Helper functions to reduce code repetition by 90%

Project Structure

mcp-prometheus/
├── cmd/                    # CLI commands and version info
├── internal/
│   ├── server/            # Server context and configuration  
│   └── tools/prometheus/  # 18 comprehensive MCP tools
├── main.go                # Application entry point
├── go.mod                 # Go dependencies
└── README.md              # This documentation

Code Quality Improvements

• 500+ lines reduced to ~85 lines in main registration
• Eliminated 255+ lines of redundant boilerplate
• Parameter helper functions for DRY parameter definitions
• Centralized client management with dynamic configuration
• Consistent error handling across all tools

Building & Testing

# Build the binary
go build -o mcp-prometheus

# Run tests
go test ./...

Authentication

Basic Authentication

export PROMETHEUS_USERNAME=myuser
export PROMETHEUS_PASSWORD=mypassword

Bearer Token Authentication

export PROMETHEUS_TOKEN=my-bearer-token

Multi-tenant Support

Perfect for Cortex, Mimir, Thanos, and other multi-tenant setups:

export PROMETHEUS_ORGID=tenant-123

Error Handling

Comprehensive error handling with detailed messages:

• Missing configuration guidance
• Authentication failure details
• Network connectivity troubleshooting
• Invalid PromQL query assistance
• Prometheus API error explanations
• Dynamic client creation error handling

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the same terms as the original Python implementation.