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 [email protected]: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: ""
  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

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)