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