mcp-prometheus

README

MCP Prometheus

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

This provides access to your Prometheus metrics and queries through standardized MCP interfaces, allowing AI assistants to execute PromQL queries and analyze your metrics data.

Features

• Execute PromQL queries against Prometheus
  • Instant queries with optional timestamp
  • Range queries with time bounds and step intervals
• Discover and explore metrics
  • List available metrics
  • Get metadata for specific metrics
  • View scrape target information
• Authentication support
  • Basic auth from environment variables
  • Bearer token auth from environment variables
  • Multi-tenant organization ID headers
• Multiple transport protocols
  • Standard I/O (stdio) - default
  • Server-Sent Events (SSE) over HTTP
  • Streamable HTTP transport
• 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: Prometheus server configuration (takes precedence over tool parameters)
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: For multi-tenant setups like Cortex, Mimir or Thanos (takes precedence over tool parameters)
export PROMETHEUS_ORGID=your_organization_id

Note: If PROMETHEUS_URL or PROMETHEUS_ORGID environment variables are not set, they can be provided as parameters to individual tool calls. Environment variables always take precedence over tool parameters when both are provided.

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_USERNAME": "your_username",
        "PROMETHEUS_PASSWORD": "your_password"
      }
    }
  }
}

Available Tools

Tool	Description	Parameters
execute_query	Execute a PromQL instant query	query (required), prometheus_url (optional), orgid (optional), time (optional), unlimited (optional)
execute_range_query	Execute a PromQL range query	query, start, end, step (all required), prometheus_url (optional), orgid (optional), unlimited (optional)
list_metrics	List all available metrics	prometheus_url (optional), orgid (optional)
get_metric_metadata	Get metadata for a specific metric	metric (required), prometheus_url (optional), orgid (optional)
get_targets	Get information about scrape targets	prometheus_url (optional), orgid (optional)

Parameter Details:

• prometheus_url: Prometheus server URL (required if PROMETHEUS_URL environment variable is not set)
• orgid: Organization ID for multi-tenant setups (optional, overridden by PROMETHEUS_ORGID environment variable if set)

Example Tool Usage

Execute an instant query

{
  "query": "up",
  "prometheus_url": "http://prometheus:9090",
  "orgid": "tenant-123",
  "time": "2023-01-01T00:00:00Z"
}

Execute a range query

{
  "query": "rate(http_requests_total[5m])",
  "prometheus_url": "http://prometheus:9090",
  "start": "2023-01-01T00:00:00Z",
  "end": "2023-01-01T01:00:00Z", 
  "step": "1m"
}

Get metric metadata

{
  "metric": "http_requests_total",
  "prometheus_url": "http://prometheus:9090"
}

Note: The prometheus_url and orgid parameters are optional if the corresponding environment variables are set.

Transport Options

The server supports multiple transport protocols:

stdio (Default)

Standard input/output - suitable for MCP clients that spawn the server as a subprocess.

./mcp-prometheus serve --transport stdio

SSE (Server-Sent Events)

HTTP-based transport using Server-Sent Events for real-time communication.

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

Access endpoints:

• SSE: http://localhost:8080/sse
• Messages: http://localhost:8080/message

Streamable HTTP

HTTP transport with streamable request/response handling.

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

Access endpoint: http://localhost:8080/mcp

Development

Requirements

• Go 1.24.4 or later
• Access to a Prometheus server for testing

Building

go build -o mcp-prometheus

Testing

go test ./...

Project Structure

mcp-prometheus/
├── cmd/                    # CLI commands
│   ├── root.go            # Root command definition
│   ├── serve.go           # Server command implementation
│   └── version.go         # Version command
├── internal/
│   ├── server/            # Server infrastructure
│   │   ├── context.go     # Server context and configuration
│   │   └── doc.go         # Package documentation
│   └── tools/
│       └── prometheus/    # Prometheus MCP tools
│           ├── client.go  # Prometheus HTTP client
│           ├── tools.go   # Tool registration and handlers
│           └── doc.go     # Package documentation
├── main.go                # Application entry point
├── go.mod                 # Go module definition
└── README.md              # This file

Architecture

The server follows a modular architecture:

• cmd/: Command-line interface using Cobra
• internal/server/: Core server infrastructure with context management
• internal/tools/prometheus/: Prometheus MCP tools
• Transport Layer: Pluggable transport protocols (stdio, SSE, HTTP)

Adding New Features

1. Extend the Prometheus client in internal/tools/prometheus/client.go
2. Add new tool definitions in internal/tools/prometheus/tools.go
3. Register tools with the MCP server
4. Update documentation

Authentication

The server supports multiple authentication methods:

Basic Authentication

export PROMETHEUS_USERNAME=myuser
export PROMETHEUS_PASSWORD=mypassword

Bearer Token Authentication

export PROMETHEUS_TOKEN=my-bearer-token

Multi-tenant Support

For Prometheus setups with tenant isolation (Cortex, Mimir, Thanos):

export PROMETHEUS_ORGID=tenant-123

Error Handling

The server provides detailed error messages for common issues:

• Missing Prometheus URL (when not provided via environment variable or tool parameter)
• Authentication failures
• Network connectivity issues
• Invalid PromQL queries
• Prometheus API errors

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.

---