Prometheus MCP Server
The Prometheus MCP Server provides a Model Context Protocol (MCP) interface for AI assistants to interact with Prometheus metrics data. You can:
Execute PromQL Queries: Run both instant queries and range queries (with specified time ranges and step intervals)
Discover Metrics: List all available metrics and retrieve metadata for specific metrics
Get Scrape Targets: Retrieve information about all configured scrape targets
Authentication Support: Connect using Basic or Bearer token authentication
Docker Deployment: Easily deploy and run using Docker or Docker Compose
Configurable Tools: Customize available tools to optimize context window usage
Provides access to Prometheus metrics and queries, allowing execution of PromQL queries, metrics discovery and exploration, viewing instant and range query results, and retrieving target information from a Prometheus server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Prometheus MCP Server show me the top 5 CPU usage metrics over the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Prometheus MCP Server
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:latestAdd 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:
Via MCP Catalog: Visit the Prometheus MCP Server on Docker Hub and click the button above
Via MCP Toolkit: Use Docker Desktop's MCP Toolkit extension to discover and install the server
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:latestDeploy 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.yamlSee the chart values for all available configuration options.
Configuration Options
Variable | Description | Required |
| URL of your Prometheus server | Yes |
| Set to False to disable SSL verification | No |
| Set to True to disable Prometheus UI links in query results (saves context tokens) | No |
| Request timeout in seconds to prevent hanging requests (DDoS protection) | No (default: 30) |
| Username for basic authentication | No |
| Password for basic authentication | No |
| Bearer token for authentication | No |
| Path to client certificate file for mutual TLS authentication | No |
| Path to client private key file for mutual TLS authentication | No |
| Path to CA bundle file for verifying the server's TLS certificate (standard | No |
| Organization ID for multi-tenant setups | No |
| Transport mode (stdio, http, sse) | No (default: stdio) |
| Host for HTTP transport | No (default: 127.0.0.1) |
| Port for HTTP transport | No (default: 8080) |
| Enable stateless HTTP mode for multi-replica support | No (default: False) |
| Custom headers as JSON string | No |
| Prefix for all tool names (e.g., | No |
Related MCP server: Prometheus MCP Server
Available Tools
Tool | Category | Description |
| System | Health check endpoint for container monitoring and status verification |
| Query | Execute a PromQL instant query against Prometheus |
| Query | Execute a PromQL range query with start time, end time, and step interval |
| Discovery | List all available metrics in Prometheus with pagination and filtering support |
| Discovery | Get metadata for one metric or bulk metadata with optional filtering |
| Discovery | Get scrape targets, with server-side |
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 | shYou 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-missingWhen adding new features, please also add corresponding tests.
License
MIT
Available Tools
6 toolsexecute_queryExecute PromQL QueryCRead-onlyIdempotent
Execute a PromQL instant query against Prometheus
Inputs: query (required), time. Returns: object
execute_range_queryExecute PromQL Range QueryBRead-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 MetadataARead-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 TargetsARead-onlyIdempotent
Get information about all scrape targets
Inputs: no named parameters. Returns: object
health_checkHealth CheckARead-onlyIdempotent
Health check endpoint for container monitoring and status verification
Inputs: no named parameters. Returns: object
list_metricsList Available MetricsARead-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
Scored across 6 tools
Each tool has a clearly distinct purpose: query types (instant vs range), metadata retrieval, target info, health check, and metric listing. No overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., execute_query, get_metric_metadata). No deviations.
Six tools cover the essential Prometheus operations without being excessive or insufficient. Well-scoped for the server's purpose.
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
Related MCP Connectors
Query your app's logs, metrics and incidents from your AI assistant.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
List datasets, schemas, run APL queries, and use prompts for exploration, anomalies, and monitoring.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA tool that enables access to Prometheus metrics data through a Model Context Protocol server, allowing interaction with monitoring data using natural language.MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to query Prometheus metrics, discover available data, and analyze system performance through natural language interactions.5224 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables 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