Skip to main content
Glama
Prometheus MCP Server

Prometheus MCP Server

by pab1it0

Prometheus MCP Server

GitHub Container Registry Helm Chart GitHub Release Codecov Python License

Give AI assistants the power to query your Prometheus metrics.

A Model Context Protocol (MCP) server that provides access to your Prometheus metrics and queries through standardized MCP interfaces, allowing AI assistants to execute PromQL queries and analyze your metrics data.

Getting Started

Prerequisites

  • Prometheus server accessible from your environment

  • MCP-compatible client (Claude Desktop, VS Code, Cursor, Windsurf, etc.)

Installation Methods

Add to your Claude Desktop configuration:

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

Install via the Claude Code CLI:

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

Add to your MCP settings in the respective IDE:

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

The easiest way to run the Prometheus MCP server is through Docker Desktop:

  1. Via MCP Catalog: Visit the Prometheus MCP Server on Docker Hub and click the button above

  2. Via MCP Toolkit: Use Docker Desktop's MCP Toolkit extension to discover and install the server

  3. Configure your connection using environment variables (see Configuration Options below)

Run directly with Docker:

# With environment variables
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

# With authentication
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  -e PROMETHEUS_USERNAME="admin" \
  -e PROMETHEUS_PASSWORD="password" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Deploy to Kubernetes using the Helm chart from the OCI registry:

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

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"

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

See the chart values for all available configuration options.

Configuration Options

Variable

Description

Required

PROMETHEUS_URL

URL of your Prometheus server

Yes

PROMETHEUS_URL_SSL_VERIFY

Set to False to disable SSL verification

No

PROMETHEUS_DISABLE_LINKS

Set to True to disable Prometheus UI links in query results (saves context tokens)

No

PROMETHEUS_REQUEST_TIMEOUT

Request timeout in seconds to prevent hanging requests (DDoS protection)

No (default: 30)

PROMETHEUS_USERNAME

Username for basic authentication

No

PROMETHEUS_PASSWORD

Password for basic authentication

No

PROMETHEUS_TOKEN

Bearer token for authentication

No

PROMETHEUS_CLIENT_CERT

Path to client certificate file for mutual TLS authentication

No

PROMETHEUS_CLIENT_KEY

Path to client private key file for mutual TLS authentication

No

REQUESTS_CA_BUNDLE

Path to CA bundle file for verifying the server's TLS certificate (standard requests library env var)

No

ORG_ID

Organization ID for multi-tenant setups

No

PROMETHEUS_MCP_SERVER_TRANSPORT

Transport mode (stdio, http, sse)

No (default: stdio)

PROMETHEUS_MCP_BIND_HOST

Host for HTTP transport

No (default: 127.0.0.1)

PROMETHEUS_MCP_BIND_PORT

Port for HTTP transport

No (default: 8080)

PROMETHEUS_MCP_STATELESS_HTTP

Enable stateless HTTP mode for multi-replica support

No (default: False)

PROMETHEUS_CUSTOM_HEADERS

Custom headers as JSON string

No

TOOL_PREFIX

Prefix for all tool names (e.g., staging results in staging_execute_query). Useful for running multiple instances targeting different environments in Cursor

No

Related MCP server: Prometheus MCP Server

Available Tools

Tool

Category

Description

health_check

System

Health check endpoint for container monitoring and status verification

execute_query

Query

Execute a PromQL instant query against Prometheus

execute_range_query

Query

Execute a PromQL range query with start time, end time, and step interval

list_metrics

Discovery

List all available metrics in Prometheus with pagination and filtering support

get_metric_metadata

Discovery

Get metadata for one metric or bulk metadata with optional filtering

get_targets

Discovery

Get scrape targets, with server-side state/scrape_pool filtering and optional pagination

The list of tools is configurable, so you can choose which tools you want to make available to the MCP client. This is useful if you don't use certain functionality or if you don't want to take up too much of the context window.

Features

  • Execute PromQL queries against Prometheus

  • Discover and explore metrics

    • List available metrics

    • Get metadata for specific metrics

    • Search metric metadata by name or description in a single call

    • View instant query results

    • View range query results with different step intervals

    • Open range query results in the Prometheus UI with the same time window and resolution

  • Authentication support

    • Basic auth from environment variables

    • Bearer token auth from environment variables

  • Docker containerization support

  • Provide interactive tools for AI assistants

Development

Contributions are welcome! Please see our Contributing Guide for detailed information on how to get started, coding standards, and the pull request process.

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 the dependencies with:

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

Testing

The project includes a comprehensive test suite that ensures functionality and helps prevent regressions.

Run the 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

When adding new features, please also add corresponding tests.

License

MIT


Available Tools

6 tools
execute_queryExecute PromQL QueryC
Read-onlyIdempotent

Execute a PromQL instant query against Prometheus

Inputs: query (required), time. Returns: object

execute_range_queryExecute PromQL Range QueryB
Read-onlyIdempotent

Execute a PromQL range query with start time, end time, and step interval

Inputs: query (required), start (required), end (required), step (required). Returns: object

get_metric_metadataGet Metric MetadataA
Read-onlyIdempotent

Get metadata (type, help, unit) for metrics. Returns all metric metadata when no metric name is provided. Use filter_pattern to search metric names and descriptions.

Inputs: metric, filter_pattern, limit, offset. Returns: result

get_targetsGet Scrape TargetsA
Read-onlyIdempotent

Get information about all scrape targets

Inputs: no named parameters. Returns: object

health_checkHealth CheckA
Read-onlyIdempotent

Health check endpoint for container monitoring and status verification

Inputs: no named parameters. Returns: object

list_metricsList Available MetricsA
Read-onlyIdempotent

List all available metrics in Prometheus with optional pagination support

Inputs: limit, offset, filter_pattern, refresh_cache. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: query types (instant vs range), metadata retrieval, target info, health check, and metric listing. No overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., execute_query, get_metric_metadata). No deviations.

    Tool Count5/5

    Six tools cover the essential Prometheus operations without being excessive or insufficient. Well-scoped for the server's purpose.

    Completeness4/5

    Core CRUD-like operations for queries and metadata are present. Minor gaps like alert management or rule configuration are missing but not critical for the primary use case.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A tool that enables access to Prometheus metrics data through a Model Context Protocol server, allowing interaction with monitoring data using natural language.
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to query Prometheus metrics, discover available data, and analyze system performance through natural language interactions.
      5
      224 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query Prometheus metrics, monitor alerts, and analyze system health through read-only access to your Prometheus server with built-in query safety and optional AI-powered metric analysis.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to execute PromQL queries and discover metrics across multiple Prometheus tenants using the Model Context Protocol. It supports single and multi-tenant configurations with secure authentication for instant and range query analysis.
      MIT

    Appeared in Searches