execute_query
Execute a PromQL instant query against Prometheus
LABSCO SUMMARY
The metric-name problem and the query get solved in the same place.
Most PromQL written from memory fails on the name or the unit rather than the logic, and the catalogue and metadata calls put both in front of you before the query runs. The targets call is the other half: when a series is missing, it distinguishes a metric that was never exported from a target that stopped being scraped.
What it is
A read path onto a Prometheus server: instant and range queries, the metric catalogue, metric metadata and scrape targets. Nothing here writes rules, silences or configuration.
What you get
- Instant PromQL queries at an optional point in time
- Range queries taking start, end and a step interval, so a window of history comes back in one call
- Metric discovery with a filter pattern and paging, for a catalogue too large to read at once
- Metadata per metric — type, help text and unit — searchable by pattern across both names and descriptions
- Scrape targets filtered by state and scrape pool, which is where a missing series usually turns out to be explained
- A health check for container monitoring
- Prometheus UI links attached to query results, and a switch to leave them off when they are costing more context than they are worth
- Two instances side by side: TOOL_PREFIX renames the tools, so a staging server and a production one do not collide in the same client
Requirements
A reachable Prometheus server and its address in PROMETHEUS_URL. Run it from the published container image, a Helm chart on Kubernetes, or locally with uv. Authentication covers what Prometheus deployments actually use: basic auth through PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD, a bearer token in PROMETHEUS_TOKEN, or mutual TLS with a client certificate and key. ORG_ID handles a multi-tenant setup, and PROMETHEUS_CUSTOM_HEADERS covers a proxy that wants its own headers. stdio by default, with HTTP or SSE and a stateless mode for running several replicas. MIT.
Setup effort
One command — 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
USE CASES
01
Answering how something has been behaving
Find the metric, read its type and unit, then run the range query over the window in question.
02
Checking the state of something right now
One instant query returns the current value, without opening the Prometheus UI.
03
Working out why a series disappeared
Look at the scrape targets by state and pool — the answer is usually a target that stopped being scraped rather than a metric that stopped existing.
04
Writing a query for a metric you have not used
Search the metadata by pattern across names and help text, so the query names a real series with the units you expect.
6 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
execute_range_query
Execute a PromQL range query with start time, end time, and step interval
get_metric_metadata
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.
get_targets
Get scrape targets, with state/pool filtering and optional pagination
health_check
Health check endpoint for container monitoring and status verification
list_metrics
List all available metrics in Prometheus with optional pagination support
BEFORE YOU INSTALL
What to know first
Tools you get
6 tools when we connected. The tool list is configurable, so an install can expose fewer, and TOOL_PREFIX renames every tool (staging gives staging_execute_query) so two instances can run side by side. All six are read-only queries.
Requires
docker on PATH
CONTEXT COST
Light Standing cost
Rated by the size of the 6 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Claude Code
TERMINAL
claude mcp add prometheus --env PROMETHEUS_URL=http://<YOUR_PROMETHEUS>:9090 -- docker run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latestMCP Clients
Claude Desktop, Cursor, Windsurf
JSON
{
"mcpServers": {
"prometheus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PROMETHEUS_URL",
"ghcr.io/pab1it0/prometheus-mcp-server:latest"
],
"env": {
"PROMETHEUS_URL": "<YOUR_PROMETHEUS_URL>"
}
}
}
}VS Code
VS CODE · JSON
{
"servers": {
"prometheus": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PROMETHEUS_URL",
"ghcr.io/pab1it0/prometheus-mcp-server:latest"
],
"env": {
"PROMETHEUS_URL": "<YOUR_PROMETHEUS_URL>"
}
}
}
}Kubernetes (Helm)
KUBERNETES (HELM) · TERMINAL
helm install prometheus-mcp-server oci://ghcr.io/pab1it0/charts/prometheus-mcp-server --version 1.1.1 --set prometheus.url="http://prometheus:9090"
