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

git clone git@github.com:uptrace/mcp.git
cd mcp

Initialize submodules

git submodule update --init --recursive

Build

go build -o mcp-server ./cmd/mcp-server

Configure

Create a config file:

cp config.yaml.example config.yaml

Edit config.yaml with your Uptrace credentials:

uptrace:
  api_url: "https://api.uptrace.dev"
  api_token: "<your-api-token>"
  project_id: 1

Run

Stdio mode (for Claude Code/Desktop):

./mcp-server --config config.yaml

HTTP mode (for web clients):

./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):

{
  "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)

1. Start the server:

   ./mcp-server --config config.yaml --http :8888

2. Add to Claude Code via CLI:

   claude mcp add --transport http uptrace http://localhost:8888/mcp

   Or configure manually in your config file:

   {
     "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

# 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.