otel-mcp

MCP server for querying Prometheus metrics and Loki logs with OIDC authentication.

Features

Query Prometheus metrics (PromQL)
Query Loki logs (LogQL)
HTTP API for K8s deployment
Service discovery (metrics, labels, log streams)

Quick Start

Local Development

# 1. Install
git clone <your-repo-url>
cd otel-mcp
uv sync

# 2. Configure .env
cp .env.example .env
# Edit .env with your Prometheus/Loki URLs

# 3. Run (stdio mode for local MCP)
uv run python -m src.server

Production (Kubernetes + Authentik)

See K8S_DEPLOYMENT.md for full deployment guide.

# Build and deploy
docker build -t your-registry/otel-mcp:latest .
kubectl apply -f k8s/

# Access at https://otel-mcp.your-domain.com

Available Tools

Prometheus (5 tools)

query_prometheus - Execute PromQL instant queries
query_prometheus_range - Query metrics over time range
list_metrics - List available metrics
list_label_values - Get label values (discover services)
list_labels - List all label names

Loki (4 tools)

query_loki - Execute LogQL queries
search_logs - Simple log search with filters
list_log_labels - List log stream labels
list_log_label_values - Get log label values

Usage

Production: K8s with Authentik OAuth Proxy

Deploy HTTP server behind Authentik for authentication.

See K8S_DEPLOYMENT.md for complete setup.

# Build and deploy
docker build -t registry/otel-mcp:latest .
kubectl apply -f k8s/

# Use the API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://otel-mcp.your-domain.com/tools

curl -X POST https://otel-mcp.your-domain.com/call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool": "query_prometheus", "arguments": {"query": "up"}}'

Local: MCP stdio (Development)

For local MCP clients like Claude Desktop.

# Run stdio server
uv run python -m src.server

# Claude Desktop config
{
  "mcpServers": {
    "otel-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/otel-mcp", "run", "python", "-m", "src.server"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090",
        "LOKI_URL": "http://localhost:3100"
      }
    }
  }
}

Configuration Options

Variable	Default	Description
`PROMETHEUS_URL`	`http://localhost:9090`	Prometheus endpoint
`LOKI_URL`	`http://localhost:3100`	Loki endpoint
`MCP_AUTH_ENABLED`	`false`	Enable OIDC auth
`MCP_OIDC_ISSUER`	-	OIDC provider URL
`MCP_OIDC_CLIENT_ID`	-	OAuth2 client ID
`MCP_OIDC_AUDIENCE`	-	Token audience (optional)
`LOG_LEVEL`	`INFO`	Logging level
`QUERY_TIMEOUT`	`30`	Query timeout (seconds)

Backend Authentication

Prometheus/Loki support Basic Auth and Bearer tokens:

# Basic Auth
PROMETHEUS_AUTH_TYPE=basic
PROMETHEUS_USERNAME=admin
PROMETHEUS_PASSWORD=secret

# Bearer Token
LOKI_AUTH_TYPE=bearer
LOKI_BEARER_TOKEN=your-token

Example Queries

# List services
{"tool": "list_label_values", "arguments": {"label": "job"}}

# Query CPU usage
{"tool": "query_prometheus", "arguments": {"query": "rate(cpu_usage[5m])"}}

# Search error logs
{"tool": "search_logs", "arguments": {"search_text": "error", "start": "1h"}}

License

MIT

opentelemetry-mcp