otel

You can run an MCP server that lets you query Prometheus metrics and Loki logs through a secure HTTP API, with optional OIDC authentication. This server helps you centralize access to metrics and logs, enabling you to discover services, run queries, and fetch logs from a single endpoint.

How to use

Use an MCP client to interact with the otel-mcp server. You can run instant Prometheus queries with query_prometheus, query ranges with query_prometheus_range, list available metrics with list_metrics, discover services via label values with list_label_values and list_labels, and query Loki logs with query_loki or search with search_logs. You can also list log streams with list_log_labels and list_log_label_values. When authentication is enabled, pass a valid OAuth2 token in the Authorization header to access protected endpoints.

How to install

Prerequisites: you need Python available to run the MCP server locally and Docker and kubectl for production deployments.

Local development steps:

# 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 deployment and access

For production deployments, you can build a Docker image and deploy to Kubernetes. Expose the service at a domain such as otel-mcp.your-domain.com. You can run the following steps to build and apply the Kubernetes manifests.

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

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

Configuration and security notes

Configure endpoints for Prometheus and Loki via environment variables. The server supports HTTP(S) access and optional OIDC authentication. The key environment variables you commonly use are:

• PROMETHEUS_URL — Prometheus endpoint (default: http://localhost:9090)
• LOKI_URL — Loki endpoint (default: http://localhost:3100)
• MCP_AUTH_ENABLED — Enable OIDC authentication (default: false)
• MCP_OIDC_ISSUER — OIDC provider URL
• MCP_OIDC_CLIENT_ID — OAuth2 client ID
• MCP_OIDC_AUDIENCE — Token audience (optional)
• LOG_LEVEL — Logging level (default: INFO)
• QUERY_TIMEOUT — Query timeout in seconds (default: 30)

Examples and usage patterns

Common API usage patterns include querying metrics, discovering services, and pulling logs. For example, you can discover services by listing label values for the job label, query CPU usage with a PromQL expression, or search for error logs. When security is enabled, include a valid Bearer token in requests.

Available tools

query_prometheus

Execute PromQL instant queries against Prometheus.

query_prometheus_range

Query metrics over a time range in Prometheus.

list_metrics

List available Prometheus metrics.

list_label_values

Get label values to discover services.

list_labels

List all label names.

query_loki

Execute LogQL queries against Loki.

search_logs

Search logs with filters.

list_log_labels

List log stream labels.

list_log_label_values

Get log label values.