📌Overview

Purpose: To provide a Model Context Protocol (MCP) server that allows access to Prometheus metrics and queries through standardized interfaces.

Overview: The Prometheus MCP Server facilitates the execution of PromQL queries, enabling AI assistants to analyze and interact with Prometheus metrics efficiently. It streamlines the process of discovering metrics, viewing results, and integrating with various authentication mechanisms.

Key Features:

Execute PromQL Queries: Allows users to perform queries against Prometheus, facilitating data retrieval and analysis.
Metric Discovery and Exploration: Provides capabilities to list available metrics, retrieve specific metric metadata, and view query results—both instant and over specified time ranges.
Authentication Support: Offers basic and bearer token authentication options for secure access to Prometheus metrics.
Docker Containerization: Supports easy deployment and isolation through Docker, simplifying the setup process.
Interactive Tools for AI Assistants: Configurable toolset allows for tailored interactions with the MCP client, optimizing the context usage for specific tasks.

Prometheus MCP Server

A Model Context Protocol (MCP) server for Prometheus.

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
Discover and explore metrics:
- List available metrics
- Get metadata for specific metrics
- View instant query results
- View range query results with different step intervals
Authentication support:
- Basic auth from environment variables
- Bearer token auth from environment variables
Docker containerization support
Provide interactive tools for AI assistants

The list of tools is configurable, so you can choose which tools to make available to the MCP client.

Usage

Ensure your Prometheus server is accessible from the environment where you'll run this MCP server.
Configure environment variables for your Prometheus server via a .env file or system environment variables:

# Required: Prometheus configuration
PROMETHEUS_URL=http://your-prometheus-server:9090

# Optional: Authentication credentials (if needed)
# Choose one of the following authentication methods if required:

# For basic auth
PROMETHEUS_USERNAME=your_username
PROMETHEUS_PASSWORD=your_password

# For bearer token auth
PROMETHEUS_TOKEN=your_token

Add the server configuration to your client configuration file. For example, for Claude Desktop:

{
  "mcpServers": {
    "prometheus": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to prometheus-mcp-server directory>",
        "run",
        "src/prometheus_mcp_server/main.py"
      ],
      "env": {
        "PROMETHEUS_URL": "http://your-prometheus-server:9090",
        "PROMETHEUS_USERNAME": "your_username",
        "PROMETHEUS_PASSWORD": "your_password"
      }
    }
  }
}

Note: if you see Error: spawn uv ENOENT in Claude Desktop, you may need to specify the full path to uv or set the environment variable NO_UV=1 in the configuration.

Docker Usage

This project includes Docker support for easy deployment and isolation.

Building the Docker Image

Build the Docker image using:

docker build -t prometheus-mcp-server .

Running with Docker

You can run the server using Docker in several ways:

Using docker run directly:

docker run -it --rm \
  -e PROMETHEUS_URL=http://your-prometheus-server:9090 \
  -e PROMETHEUS_USERNAME=your_username \
  -e PROMETHEUS_PASSWORD=your_password \
  prometheus-mcp-server

Using docker-compose:

Create a .env file with your Prometheus credentials and then run:

docker-compose up

Running with Docker in Claude Desktop

To use the containerized server with Claude Desktop, update the configuration to use Docker with the environment variables:

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "PROMETHEUS_URL",
        "-e", "PROMETHEUS_USERNAME",
        "-e", "PROMETHEUS_PASSWORD",
        "prometheus-mcp-server"
      ],
      "env": {
        "PROMETHEUS_URL": "http://your-prometheus-server:9090",
        "PROMETHEUS_USERNAME": "your_username",
        "PROMETHEUS_PASSWORD": "your_password"
      }
    }
  }
}

This configuration passes environment variables from Claude Desktop to the Docker container using the -e flag with just the variable name, and providing actual values in the env object.

Note about Docker implementation: The Docker setup uses a multi-stage build and runs the entry point script directly without an intermediary shell script. This ensures proper handling of stdin/stdout for MCP communication.

Development

Contributions are welcome! Please open an issue or submit a pull request if you have suggestions or improvements.

This project uses uv to manage dependencies. Install uv following the instructions for your platform:

curl -LsSf https://astral.sh/uv/install.sh | sh

You can then create a virtual environment and install dependencies with:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Project Structure

The project is organized with a src directory structure:

prometheus-mcp-server/
├── src/
│   └── prometheus_mcp_server/
│       ├── __init__.py      # Package initialization
│       ├── server.py        # MCP server implementation
│       ├── main.py          # Main application logic
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose configuration
├── .dockerignore            # Docker ignore file
├── pyproject.toml           # Project configuration
└── README.md                # This file

Testing

The project includes a comprehensive test suite to ensure functionality and prevent regressions.

Run tests with pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Tests cover:

Configuration validation
Server functionality
Error handling
Main application

Please add corresponding tests when adding new features.

Tools

Tool	Category	Description
`execute_query`	Query	Execute a PromQL instant query against Prometheus
`execute_range_query`	Query	Execute a PromQL range query with start/end time, step
`list_metrics`	Discovery	List all available metrics in Prometheus
`get_metric_metadata`	Discovery	Get metadata for a specific metric
`get_targets`	Discovery	Get information about all scrape targets

License

MIT