io.github.jeanlopezxyz/mcp-prometheus

Prometheus MCP Server (Go)

A Model Context Protocol (MCP) server for Prometheus integration. Native Go binary with built-in Kubernetes connectivity via client-go.

Installation

npx

npx -y mcp-prometheus@latest

MCP Client Configuration

Add to your MCP client configuration (VS Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["-y", "mcp-prometheus@latest"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

VS Code

code --add-mcp '{"name":"prometheus","command":"npx","args":["-y","mcp-prometheus@latest"],"env":{"PROMETHEUS_URL":"http://localhost:9090"}}'

Kubernetes Auto-Connect

Automatically connects to Prometheus running in OpenShift/Kubernetes via the K8S API service proxy. Uses native kubeconfig/in-cluster config via client-go. No kubectl or port-forwarding required.

Default: openshift-monitoring/prometheus-operated:9090

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["-y", "mcp-prometheus@latest"]
    }
  }
}

Binary

Download from GitHub Releases or build from source:

make build
./mcp-prometheus

---

Configuration

Environment Variables

Variable	Description
PROMETHEUS_URL	Direct Prometheus API URL (overrides K8S auto-connect)

CLI Flags

Flag	Description	Default
--url	Direct Prometheus URL	-
--namespace	Kubernetes namespace	openshift-monitoring
--service	Kubernetes service name	prometheus-operated
--service-port	Kubernetes service port	9090
--service-scheme	Service scheme (http/https)	https
--kubeconfig	Path to kubeconfig file	auto-detect

Precedence: --url / PROMETHEUS_URL > K8S auto-connect

Connection strategy:

1. Direct URL (if --url or PROMETHEUS_URL is set)
2. K8S API proxy (auto-detect kubeconfig or in-cluster config)

---

Tools (11)

Basic Queries

Tool	Description
query	Execute a PromQL instant query
queryRange	Execute a PromQL range query over time
getTargets	Get scrape targets status
getRules	Get alerting and recording rules
getPrometheusStatus	Get server version and runtime info

Cluster Diagnostics

Tool	Description
getClusterHealthOverview	Comprehensive cluster health overview
diagnoseNode	Diagnose a specific node's health
diagnoseNamespace	Diagnose a namespace's health

Resource Analysis

Tool	Description
getTopResourceConsumers	Top CPU/memory/network consumers
investigatePod	Deep investigation of a specific pod
compareTimeRanges	Compare metrics between two time periods

---

Example Prompts

"What's the current CPU usage across all nodes?"
"Show me the cluster health overview"
"Which pods are using the most memory?"
"Diagnose node worker-1"
"Are all scrape targets healthy?"
"Compare CPU usage now vs 24 hours ago"
"Investigate pod my-app in namespace production"
"What alerting rules are defined?"

---

Development

Build

make build              # Build for current platform
make build-all-platforms # Cross-compile for all platforms

Container

podman build -f Containerfile -t mcp-prometheus .

---

Kubernetes / OpenShift Deployment

Container Image

The container image is available on GitHub Container Registry:

ghcr.io/jeanlopezxyz/mcp-prometheus:latest

Helm Chart

Deploy using the included Helm chart:

# Add the chart repository (or use local chart)
helm upgrade --install mcp-prometheus ./charts/mcp-prometheus \
  --namespace mcp-servers \
  --create-namespace \
  --set openshift=true

Helm Values

Parameter	Description	Default
image.registry	Container registry	ghcr.io
image.repository	Image repository	jeanlopezxyz/mcp-prometheus
image.version	Image tag	latest
openshift	Enable OpenShift Routes	false
service.port	Service port	8080
prometheus.namespace	Prometheus namespace	openshift-monitoring
prometheus.service	Prometheus service name	prometheus-operated
rbac.useClusterReader	Use cluster-reader role	true

Example with custom Prometheus

helm upgrade --install mcp-prometheus ./charts/mcp-prometheus \
  --namespace mcp-servers \
  --set openshift=true \
  --set prometheus.url=http://prometheus.monitoring:9090

---

License

MIT