Uptrace MCP Server
A Model Context Protocol (MCP) server for Uptrace, written in Go.
Overview
This server implements the Model Context Protocol to expose Uptrace observability data to AI assistants and LLM-powered tools.
Prerequisites
- Go 1.21+
- Access to an Uptrace instance
Getting Started
Clone the repository```bash
git clone git@github.com:uptrace/mcp.git
cd mcp
### Initialize submodules```bash
git submodule update --init --recursive
Build```bash
go build -o mcp-server ./cmd/mcp-server
### Configure
Create a config file:```bash
cp config.yaml.example config.yaml
Edit config.yaml with your Uptrace credentials:```yaml
uptrace:
api_url: "https://api.uptrace.dev"
api_token: "<your-api-token>"
project_id: 1
### Run
**Stdio mode** (for Claude Code/Desktop):```bash
./mcp-server --config config.yaml
HTTP mode (for web clients):```bash
./mcp-server --config config.yaml --http :8080
## Adding to Claude Code
Claude Code supports two transport modes for MCP servers:
### Option 1: Stdio Mode (Recommended)
Claude spawns the server as a subprocess. Add to `~/.claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):```json
{
"mcpServers": {
"uptrace": {
"command": "/path/to/mcp-server",
"args": ["--config", "/path/to/config.yaml"]
}
}
}
Replace /path/to/mcp-server and /path/to/config.yaml with absolute paths.
Option 2: HTTP Mode
Run the server separately and connect via HTTP. This is useful for:
- Sharing one server across multiple clients
- Running the server on a remote machine
- Development with hot-reload (task dev)
-
Start the server:
bash ./mcp-server --config config.yaml --http :8888 -
Add to Claude Code via CLI:
bash claude mcp add --transport http uptrace http://localhost:8888/mcp
Or configure manually in your config file:json
{
"mcpServers": {
"uptrace": {
"url": "http://localhost:8888/mcp"
}
}
}
Available Tools
| Tool | Description |
|---|---|
list_span_groups |
Aggregate spans using UQL (Uptrace Query Language). Group and analyze spans by attributes. |
list_spans |
List spans from Uptrace. Supports time range filtering, trace ID filtering, and pagination. |
list_monitors |
List monitors from Uptrace. View configured alerts and monitoring rules. |
list_span_groups
Aggregate spans using UQL (Uptrace Query Language) for grouping and analysis.
Parameters:
- time_start (optional): Start time in RFC3339 format, defaults to 1 hour ago
- time_end (optional): End time, defaults to now
- query (optional): UQL query string
- search (optional): Search filter
- duration_gte (optional): Filter spans with duration >= value (nanoseconds)
- duration_lt (optional): Filter spans with duration < value (nanoseconds)
- limit (optional): Maximum number of groups to return (default: 100, max: 10000)
UQL query examples:
- group by host_name - group spans by hostname
- group by service_name - group spans by service
- where _status_code = "error" | group by service_name - group errors by service
- group by service_name | having count() > 100 - services with >100 spans
- where _dur_ms > 1s | group by _name - slow operations
Example usage in Claude:
> "Group spans by service name"
> "Show me error rates by host"
list_spans
Fetch spans from Uptrace for analyzing distributed traces.
Parameters:
- time_start (optional): Start time in RFC3339 format, defaults to 1 hour ago
- time_end (optional): End time, defaults to now
- trace_id (optional): Filter by specific trace ID
- limit (optional): Maximum number of spans to return (default: 100)
Example usage in Claude:
> "Show me spans from the last hour"
> "Find spans for trace ID abc123"
list_monitors
Fetch configured monitors (alerts) from Uptrace.
Parameters: None (uses project_id from config)
Example usage in Claude:
> "List all monitors"
> "Show me the configured alerts"
Configuration
| Field | Required | Description |
|---|---|---|
uptrace.dsn |
No | DSN connection string (alternative to individual fields) |
uptrace.api_url |
Yes | Uptrace API URL |
uptrace.api_token |
Yes | API token for authentication |
uptrace.project_id |
Yes | Uptrace project ID |
logging.level |
No | Log level: debug, info, warn, error (default: info) |
logging.max_body_size |
No | Maximum body size for logging |
service.start_timeout |
No | Service start timeout (default: 15s) |
service.stop_timeout |
No | Service stop timeout (default: 15s) |
Development```bash
Run with hot-reload
task dev
Run tests
task test
Regenerate API client
task generate
```
See AGENTS.md for coding guidelines and project documentation.
License
See LICENSE for details.
