🚀 Prometheus MCP Server: Supercharge Your LLMs with Real-Time Metrics 📊

Unlock the power of your Prometheus metrics within your Large Language Model (LLM) applications with the Prometheus Model Context Protocol (MCP) Server. This server acts as a bridge, enabling seamless communication between your LLMs and Prometheus, allowing AI assistants to execute PromQL queries and gain valuable insights from your monitoring data.

✨ Key Features

• PromQL Execution: Execute instant and range PromQL queries directly against your Prometheus instance.
• Metric Discovery:
  • List all available metrics.
  • Retrieve detailed metadata for specific metrics.
  • Explore instant query results.
  • Analyze range query results with customizable step intervals.
• Authentication: Secure access to your Prometheus data with:
  • Basic Authentication (username/password).
  • Bearer Token Authentication.
• Containerization: Effortless deployment and isolation with Docker support.
• Interactive AI Tools: Empower your AI assistants with a suite of tools for interacting with Prometheus.
  • Configurable toolset to optimize context window usage.

🛠️ Getting Started

Prerequisites

• Ensure your Prometheus server is accessible from the environment where the MCP server will run.

Configuration

1. Environment Variables: Configure the following environment variables, either in a .env file or directly in your system environment:

   # Required: Prometheus URL
   PROMETHEUS_URL=http://your-prometheus-server:9090
   
   # Optional: Authentication (choose one method)
   # Basic Auth:
   PROMETHEUS_USERNAME=your_username
   PROMETHEUS_PASSWORD=your_password
   
   # Bearer Token:
   PROMETHEUS_TOKEN=your_token

2. Client Configuration: Integrate the server into your LLM client configuration. Here's an 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"
         }
       }
     }
   }

   • Troubleshooting: If you encounter Error: spawn uv ENOENT, provide the full path to the uv executable or set NO_UV=1 in the configuration.

🐳 Docker Deployment

Simplify deployment with Docker!

Building the Image

docker build -t prometheus-mcp-server .

Running the Container

Option 1: docker run

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

Option 2: docker-compose

1. Create a .env file with your Prometheus credentials.
2. Run: docker-compose up

Claude Desktop with Docker

Configure Claude Desktop to use the containerized server:

{
  "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.

🧑‍💻 Development

Contributions are highly encouraged! Feel free to open issues or submit pull requests.

Setup

1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Create a virtual environment: uv venv
3. Activate the environment:
   • Unix/macOS: source .venv/bin/activate
   • Windows: .venv\Scripts\activate
4. Install dependencies: uv pip install -e .

Project 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

Ensure code quality with our comprehensive test suite.

1. Install development dependencies: uv pip install -e ".[dev]"
2. Run tests: pytest
3. Run with coverage report: pytest --cov=src --cov-report=term-missing

Available Tools

By leveraging the Prometheus MCP Server, you can empower your LLMs with real-time monitoring data, enabling them to make more informed decisions and provide more insightful responses.