Prometheus MCP Server

This project uses uv for dependency management. To set up a local development environment:

1. Install uv:

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

2. Create a virtual environment and install dependencies:

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

Once the server is installed in your cluster, you can access the MCP endpoint locally by port-forwarding the service. The MCP endpoint will be available at http://127.0.0.1:8080/sse (assuming default port 8080).

kubectl port-forward svc/prometheus-mcp-server 8080:8080

You can install the server directly using the Claude Code CLI by providing the Prometheus URL as an environment variable.

claude mcp add prometheus --env PROMETHEUS_URL=http://your-prometheus:9090 -- docker run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latest

To use the Prometheus MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json file. This setup uses Docker to run the server and passes the PROMETHEUS_URL via environment variables.

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PROMETHEUS_URL",
        "ghcr.io/pab1it0/prometheus-mcp-server:latest"
      ],
      "env": {
        "PROMETHEUS_URL": "<your-prometheus-url>"
      }
    }
  }
}

The project uses pytest for testing. To run the test suite, first install the development dependencies, then execute pytest.

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

# Run the tests
pytest

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

Deploy the server to a Kubernetes cluster using the official Helm chart from the OCI registry. You can set the Prometheus URL and authentication credentials via --set flags.

# Basic installation
helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090"

# Installation with authentication
helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090" \
  --set auth.username="admin" \
  --set auth.password="secret"

# Installation with a custom values file
helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  -f values.yaml

You can install the Prometheus MCP Server to your Kubernetes cluster using either the OCI registry or by cloning the source repository.

Prerequisites

• Kubernetes >= 1.19
• Helm >= 3.0
• A Prometheus instance accessible from the cluster

Installation via OCI Registry

Use the following command to install directly from the GitHub Container Registry:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --set prometheus.url=http://prometheus:9090

Installation from Source

Clone the repository and install from the local chart directory:

git clone https://github.com/pab1it0/prometheus-mcp-server.git
cd prometheus-mcp-server

helm install prometheus-mcp-server ./charts/prometheus-mcp-server \
  --set prometheus.url=http://prometheus:9090

Add the server configuration to your IDE's MCP settings. This configuration runs the server via Docker.

{
  "prometheus": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "PROMETHEUS_URL",
      "ghcr.io/pab1it0/prometheus-mcp-server:latest"
    ],
    "env": {
      "PROMETHEUS_URL": "<your-prometheus-url>"
    }
  }
}

The server supports three authentication modes for connecting to your Prometheus instance based on the provided environment variables:

1. Basic Auth: Set both PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD.
2. Bearer Token: Set PROMETHEUS_TOKEN.
3. None: If no credentials are provided, the server attempts to connect without authentication.

Configure how the MCP server connects to your Prometheus instance using the following parameters:

Control the MCP server's behavior and tool presentation using these parameters: