Uptrace MCP Server

Uptrace MCP Server

Model Context Protocol (MCP) server for Uptrace observability platform. Provides tools for querying traces, spans, and errors through Claude Desktop or other MCP clients.

Features

• 🔍 Query error spans - Get detailed error information with traces and stack traces
• 📊 Query spans - Filter and search spans using Uptrace Query Language (UQL)
• 🔗 Trace visualization - Get full trace trees with all related spans
• 📈 Aggregations - Group and aggregate spans by services, operations, etc.
• 📝 Query logs - Search and filter logs by severity, service, and custom UQL queries
• 📉 Query metrics - Query metrics using PromQL-compatible syntax
• 🏷️ Service discovery - List all services reporting telemetry data
• 📚 Query syntax documentation - Get comprehensive UQL syntax reference

Installation

Prerequisites

• Python 3.10 or higher
• Poetry (recommended) or pip
• Uptrace instance (self-hosted or cloud)

Using uv (recommended)

uvx --from . uptrace-mcp

Using pip

pip install -e .

Configuration

Create a .env file in the project root or set environment variables:

UPTRACE_URL=https://uptrace.xxx
UPTRACE_PROJECT_ID=3
UPTRACE_API_TOKEN=your_token_here

You can also use a YAML file for configuration by passing the --config parameter.

# config.yaml
uptrace:
  api_url: "https://uptrace.example.com"
  project_id: "1"
  api_token: "your-api-token"
logging:
  level: debug
  file: "/path/to/uptrace-mcp.log"

The logging section is optional. By default, the server logs to standard error (stderr) at the INFO level.

Getting your Uptrace API token

1. Log in to your Uptrace instance
2. Go to your user profile
3. Navigate to "Auth Tokens" section
4. Create a new token with read access

Note: User auth tokens do not work with Single Sign-On (SSO). If using SSO, create a separate user account with API access.

Usage

As MCP Server

Cursor IDE

📖 Detailed setup guide: See CURSOR_SETUP.md for comprehensive instructions.

To add this MCP server to Cursor:

1. Open Cursor Settings (Cmd+, on macOS or Ctrl+, on Windows/Linux)
2. Search for "MCP" or navigate to Features → Model Context Protocol
3. Click Edit Config or open the MCP configuration file directly

The configuration file location:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Quick setup: You can use the example configuration file cursor-mcp-config.json.example as a template. Copy it to your Cursor MCP settings file and update the paths and credentials.

Important: The cwd parameter specifies the working directory where the command will be executed. This must be the root directory of your uptrace-mcp project (where pyproject.toml is located).

Add the following configuration (replace the paths with your actual project paths):

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/path/to/uptrace-mcp", "uptrace-mcp"],
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or using a config file:

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/path/to/uptrace-mcp", "uptrace-mcp", "--config", "/path/to/config.yaml"]
    }
  }
}

Configuration parameters:

• command - Should be uvx
• args - Arguments passed to the command (["--from", "project_path", "uptrace-mcp"])
• env - Environment variables for the server (can be omitted if using --config)

After saving the configuration, restart Cursor. The Uptrace tools will be available in the MCP tools panel.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "uptrace": {
      "command": "uvx",
      "args": ["--from", "/Users/your-username/work/pet/uptrace-mcp", "uptrace-mcp"],
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop and the Uptrace tools will be available.

Running Directly

# Using uv
uv run uptrace-mcp

# Or if installed with pip
uptrace-mcp

# With config
uv run uptrace-mcp --config config.yaml

Available Tools

Spans & Traces

`uptrace_search_spans`

Search spans with custom filters using UQL. Use where _status_code = "error" to find error spans.

Parameters:

• time_gte (required): Start time in