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

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_execute_query`	Execute PromQL instant query	`query`	`prometheus_url`, `org_id`, `time`, `timeout`, `limit`, `stats`, `lookback_delta`, `unlimited`
`mcp_prometheus_execute_range_query`	Execute PromQL range query	`query`, `start`, `end`, `step`	`prometheus_url`, `org_id`, `timeout`, `limit`, `stats`, `lookback_delta`, `unlimited`

📊 Metrics Discovery Tools

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_list_metrics`	List all available metrics	-	`prometheus_url`, `org_id`, `start_time`, `end_time`, `matches`
`mcp_prometheus_get_metric_metadata`	Get metadata for specific metric	`metric`	`prometheus_url`, `org_id`, `limit`

🏷️ Label & Series Discovery Tools

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_list_label_names`	Get all available label names	-	`prometheus_url`, `org_id`, `start_time`, `end_time`, `matches`, `limit`
`mcp_prometheus_list_label_values`	Get values for specific label	`label`	`prometheus_url`, `org_id`, `start_time`, `end_time`, `matches`, `limit`
`mcp_prometheus_find_series`	Find series by label matchers	`matches`	`prometheus_url`, `org_id`, `start_time`, `end_time`, `limit`

🎯 Target & System Information Tools

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_get_targets`	Get scrape target information	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_build_info`	Get Prometheus build information	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_runtime_info`	Get Prometheus runtime information	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_flags`	Get Prometheus runtime flags	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_config`	Get Prometheus configuration	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_tsdb_stats`	Get TSDB cardinality statistics	-	`prometheus_url`, `org_id`, `limit`

🚨 Alerting & Rules Tools

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_get_alerts`	Get active alerts	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_alertmanagers`	Get AlertManager discovery info	-	`prometheus_url`, `org_id`
`mcp_prometheus_get_rules`	Get recording and alerting rules	-	`prometheus_url`, `org_id`

🔬 Advanced Tools

Tool	Description	Required Parameters	Optional Parameters
`mcp_prometheus_query_exemplars`	Query exemplars for traces	`query`, `start`, `end`	`prometheus_url`, `org_id`
`mcp_prometheus_get_targets_metadata`	Get metadata from specific targets	-	`prometheus_url`, `org_id`, `match_target`, `metric`, `limit`

🔧 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

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

License

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

MCP Prometheus

MCP Prometheus

Features

🔍 Query Execution

📊 Metrics Discovery

🏷️ Label & Series Discovery

🎯 Target & System Information

🚨 Alerting & Rules

🔬 Advanced Features

🔐 Authentication & Transport

Installation

Pre-built Binaries

From Source

Configuration

Usage

Command Line

MCP Client Configuration

Available Tools

🔍 Query Execution Tools

📊 Metrics Discovery Tools

🏷️ Label & Series Discovery Tools

🎯 Target & System Information Tools

🚨 Alerting & Rules Tools

🔬 Advanced Tools

🔧 Enhanced Parameters

Example Usage

Basic Query Execution

Enhanced Query with Performance Options

Range Query with Time Bounds

Label Discovery with Filtering

Series Discovery

Multi-tenant Query

Query Result Optimization

Transport Options

stdio (Default)

SSE (Server-Sent Events)

Streamable HTTP

Development

Architecture

Project Structure

Code Quality Improvements

Building & Testing

Authentication

Basic Authentication

Bearer Token Authentication

Multi-tenant Support

Error Handling

Contributing

License

Related Servers

Kubernetes MCP Server

fal-ai/minimax/image-01

Alpha Ticker MCP

Beyond Menu Salesforce MCP

ALECS - MCP Server for Akamai

Google Admin MCP

Google Cloud Run

CData Zuora MCP Server

OpenAI

Shopify MCP Server