Uptrace

You can run and manage the Uptrace MCP Server locally to query traces, spans, errors, logs, and metrics from Uptrace using MCP clients such as Cursor or Claude Desktop. This server provides practical tooling to explore distributed traces and related data across your services.

How to use

Use the MCP server to connect your MCP client to your Uptrace instance and start querying data right away. You can run the server locally, then add it to your MCP client configuration so you can search spans, view traces, fetch logs and metrics, and perform aggregations across your services. The server exposes tools with clear names you can invoke from your MCP client, and you supply your Uptrace endpoint and project credentials via environment variables.

How to install

Prerequisites you need to prepare before installing the MCP server:

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

Configuring and running the MCP server

The MCP server connects to Uptrace using environment variables. Provide the Uptrace URL, the project ID, and an API token to authorize requests, then run the MCP server using your preferred local setup.

{
  "mcpServers": {
    "uptrace": {
      "type": "stdio",
      "name": "uptrace",
      "command": "/path/to/uptrace-mcp/.venv/bin/poetry",
      "args": ["run", "uptrace-mcp"],
      "cwd": "/path/to/uptrace-mcp",
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

{
  "mcpServers": {
    "uptrace": {
      "type": "stdio",
      "name": "uptrace",
      "command": "/Users/dimonb/work/pet/uptrace-mcp/.venv/bin/python",
      "args": ["-m", "uptrace_mcp.server"],
      "cwd": "/Users/dimonb/work/pet/uptrace-mcp",
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

{
  "mcpServers": {
    "uptrace": {
      "type": "stdio",
      "name": "uptrace",
      "command": "poetry",
      "args": ["run", "uptrace-mcp"],
      "cwd": "/Users/your-username/work/pet/uptrace-mcp",
      "env": {
        "UPTRACE_URL": "https://uptrace.xxx",
        "UPTRACE_PROJECT_ID": "3",
        "UPTRACE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Running directly

You can run the MCP server directly after setting the required environment variables. Use Poetry to start or install with pip if you prefer. The final start command is what you will use in your MCP client configuration.

Troubleshooting and tips

If you encounter issues, verify that the working directory and environment variables are correctly set, ensure the Uptrace URL and project ID are valid, and confirm that the API token has the proper permissions. Restart your MCP client after updating the configuration. If there are permission or 403 errors, check token scope and SSO settings. If you receive no data, broaden the time range and confirm data exists in Uptrace.

Notes on usage

The MCP server exposes tools to search spans, get traces, group and aggregate results, query logs, and query metrics with PromQL-compatible syntax. Use the provided tool names to perform actions and consult the Uptrace query language syntax for advanced filtering and aggregation.

Available tools

uptrace_search_spans

Search spans with custom filters using UQL to filter by service, status, or other fields.

uptrace_get_trace

Retrieve all spans for a specific trace ID to inspect a full trace.

uptrace_search_groups

Group and aggregate spans by specified fields, such as service_name, with optional counts and metrics.

uptrace_search_services

Discover services that have reported telemetry within a selected time window.

uptrace_search_logs

Query logs by text, severity, service name, or custom UQL filters, including time range.

uptrace_get_query_syntax

Return comprehensive UQL syntax documentation for spans, logs, and metrics.

get_span_by_id

Fetch a specific span by its ID.

get_spans_by_parent

Get child spans by parent span ID.

get_spans_by_system

Filter spans by system type such as http, db, or rpc.

get_slow_spans

Identify spans that exceed a duration threshold.

get_query_syntax

Obtain comprehensive UQL syntax details for reference.