Configuration

Complete configuration guide for the Prometheus MCP Server including environment variables, Docker setup, multi-backend configuration, and Kubernetes integration.

---

Prerequisites

Requirement	Description
Prometheus	Access to a Prometheus-compatible backend (Prometheus, Thanos, Mimir, Cortex, or VictoriaMetrics)
Docker	For containerized deployment (recommended)
Python 3.12+	For local development
Kubernetes	Optional — required for exporter deployment, ServiceMonitor, and CRD features
Prometheus Operator	Optional — required for prom_apply_servicemonitor and CRD rule upsert

---

Installation Options

Option 1: Docker (Recommended)

# Pull the latest image
docker pull talkopsai/prometheus-mcp-server:latest

# Run with default configuration
docker run --rm -it \
  -p 8767:8767 \
  -e PROMETHEUS_BASE_URL=http://host.docker.internal:9090 \
  -e MCP_TRANSPORT=http \
  talkopsai/prometheus-mcp-server:latest

# Run with Kubernetes access
docker run --rm -it \
  -p 8767:8767 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e PROMETHEUS_BASE_URL=http://host.docker.internal:9090 \
  -e MCP_TRANSPORT=http \
  -e K8S_ENABLED=true \
  talkopsai/prometheus-mcp-server:latest

Option 2: From Source (Python)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/prometheus-mcp-server

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Configure .env
cp .env.example .env
# Edit .env — at minimum set PROMETHEUS_BASE_URL

# Run the server
uv run prometheus-mcp-server

Run tests (with the venv activated):

pytest tests/

---

Environment Variables

Server Configuration

Variable	Default	Description
MCP_SERVER_NAME	prometheus-mcp-server	Server name identifier
MCP_SERVER_VERSION	0.1.0	Server version string
MCP_TRANSPORT	stdio	Transport mode: http, sse, streamable-http, or stdio
MCP_HOST	0.0.0.0	Host address for HTTP server
MCP_PORT	8767	Port for HTTP server
MCP_PATH	/mcp	MCP endpoint path
MCP_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR
MCP_LOG_FORMAT	json	Log format: json or text
MCP_HTTP_TIMEOUT	300	HTTP server timeout (seconds)
MCP_HTTP_KEEPALIVE_TIMEOUT	5	HTTP keepalive timeout (seconds)
MCP_HTTP_CONNECT_TIMEOUT	60	HTTP connect timeout (seconds)

Prometheus Backend (Single)

Variable	Default	Description
PROMETHEUS_BASE_URL	http://localhost:9090	Prometheus HTTP API base URL
PROMETHEUS_BACKEND_ID	default	Backend identifier used in all tool calls
PROMETHEUS_TYPE	prometheus	Backend type: prometheus, thanos, mimir, cortex, victoriametrics, other
PROMETHEUS_DISPLAY_NAME	(empty)	Human-readable backend name
PROMETHEUS_AUTH_HEADER	(empty)	Authorization header value (e.g. Bearer <token>)
PROMETHEUS_VERIFY_SSL	true	Verify SSL certificates
PROMETHEUS_TIMEOUT	30	HTTP timeout for Prometheus API calls (seconds)

Prometheus Backends (Multi)

For multiple backends, set PROMETHEUS_BACKENDS as a JSON array:

PROMETHEUS_BACKENDS='[
  {"id": "prod", "base_url": "https://prom-prod.example.com", "type": "prometheus", "labels": {"env": "prod"}},
  {"id": "staging", "base_url": "https://thanos-staging.example.com", "type": "thanos", "labels": {"env": "staging"}}
]'

When PROMETHEUS_BACKENDS is set, the single-backend env vars (PROMETHEUS_BASE_URL, etc.) are ignored. Each backend requires a unique id that becomes the backend_id in all tool calls.

Kubernetes

Variable	Default	Description
K8S_CONTEXT	(empty)	Specific K8s context to use
K8S_IN_CLUSTER	false	Set true when running inside a pod
K8S_ENABLED	true	Enable Kubernetes integration

---

MCP Client Configuration

The server listens on http://localhost:8767/mcp by default. Add this to your MCP client config:

{
  "mcpServers": {
    "prometheus": {
      "url": "http://localhost:8767/mcp",
      "description": "MCP Server for Prometheus observability and monitoring management"
    }
  }
}

For stdio transport (local process communication):

{
  "mcpServers": {
    "prometheus": {
      "command": "uv",
      "args": ["run", "prometheus-mcp-server"],
      "env": {
        "PROMETHEUS_BASE_URL": "http://localhost:9090",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

---

Troubleshooting

Backend Connection Issues

1. Verify PROMETHEUS_BASE_URL points to a reachable Prometheus instance
2. Load the prom://system/backends resource to check health status
3. If using auth, verify PROMETHEUS_AUTH_HEADER is set correctly
4. For SSL issues, try PROMETHEUS_VERIFY_SSL=false (development only)

Kubernetes Integration Issues

1. Ensure K8S_ENABLED=true and your kubeconfig is accessible
2. For in-cluster deployment, set K8S_IN_CLUSTER=true
3. ServiceMonitor creation requires Prometheus Operator installed in the cluster

Query Timeout or Large Results

1. The server auto-downsamples range queries to ~200 points per series
2. Increase MCP_HTTP_TIMEOUT for slow backends
3. Response limiting middleware caps payloads at 100KB — use more specific queries

---

Next Steps

• Tools — Full reference for all 28 MCP tools
• Resources — 14 MCP resources for discovery and monitoring
• Common Workflows — Step-by-step workflow guides
• Examples — Quick reference and natural language prompts