# 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
```bash
# 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](./K8S_DEPLOYMENT.md) for full deployment guide.
```bash
# 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](./K8S_DEPLOYMENT.md) for complete setup.
```bash
# 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.
```bash
# 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:
```bash
# 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
```bash
# 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