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 ISO format (YYYY-MM-DDTHH:MM:SSZ)

• time_lt (required): End time in ISO format (YYYY-MM-DDTHH:MM:SSZ)

• query (optional): UQL query string

• limit (optional): Maximum spans to return (default: 100)

Examples:

Search spans where service_name = "aktar" and http_status_code = 404
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z

Find error spans: where _status_code = "error"
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z

uptrace_get_trace

Get all spans for a specific trace ID.

Parameters:

• trace_id (required): Trace ID to retrieve

Example:

Get trace with ID 301015e15d95f1ea12af767ebf0ffcca

uptrace_search_groups

Search and aggregate spans by groups.

Parameters:

• time_gte (required): Start time in ISO format

• time_lt (required): End time in ISO format

• query (required): UQL query with grouping

• limit (optional): Maximum groups to return (default: 100)

Example:

Group spans by service_name and count errors
from 2025-12-08T09:00:00Z to 2025-12-08T10:00:00Z
query: "where _status_code = 'error' | group by service_name | count()"

uptrace_search_services

Search for services that have reported spans.

Parameters:

• hours (optional): Number of hours to look back (default: 24)

Example:

Search for all services from the last 48 hours

Logs

uptrace_search_logs

Search logs by text, severity, service name, or custom UQL query.

Parameters:

• hours (optional): Number of hours to look back (default: 3)

• search_text (optional): Text to search for in log messages (case-insensitive)

• severity (optional): Filter by log severity (DEBUG, INFO, WARN, ERROR, FATAL)

• service_name (optional): Filter by service name

• query (optional): Additional UQL query string for advanced filtering

• limit (optional): Maximum number of logs to return (default: 100)

Examples:

Search logs containing "error" from the last 3 hours
Search ERROR level logs from service "aktar" in the last 6 hours

Documentation

uptrace_get_query_syntax

Get UQL (Uptrace Query Language) syntax documentation. Returns operators, functions, examples, and common patterns for querying spans, logs, and metrics.

Parameters:

• None

Example:

Get UQL query syntax documentation

Logs

The client provides methods for querying logs (logs are represented as spans with _system = "log:all"):

• query_logs() - Query logs with filters by severity, service name, and custom UQL queries

• get_error_logs() - Get error logs (ERROR and FATAL severity levels)

Example usage:

from datetime import datetime, timedelta
from uptrace_mcp.client import UptraceClient

client = UptraceClient(
    base_url="https://uptrace.xxx",
    project_id="3",
    api_token="your_token"
)

# Get error logs from the last hour
time_lt = datetime.utcnow()
time_gte = time_lt - timedelta(hours=1)

logs = client.get_error_logs(time_gte=time_gte, time_lt=time_lt, limit=100)

# Query logs with custom filters
logs = client.query_logs(
    time_gte=time_gte,
    time_lt=time_lt,
    severity="ERROR",
    service_name="my-service",
    query='where log_message contains "database"',
    limit=50
)

Metrics

The client provides methods for querying metrics using PromQL-compatible syntax:

• query_metrics() - Query metrics with PromQL-compatible format

• query_metrics_groups() - Query and aggregate metrics by groups

Example usage:

# Query metrics
result = client.query_metrics(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["system_cpu_utilization as $cpu"],
    query=["avg($cpu) as cpu_avg"]
)

# Query metrics with grouping
result = client.query_metrics_groups(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["uptrace_tracing_spans as $spans"],
    query=["sum($spans) as total_spans"],
    group_by=["service_name"]
)

Additional Span Methods

The client also provides additional convenience methods for working with spans:

• get_span_by_id() - Get 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 (http, db, rpc, etc.)

• get_slow_spans() - Get spans exceeding a duration threshold

• get_query_syntax() - Get comprehensive UQL syntax documentation

Example:

# Get query syntax documentation
syntax = client.get_query_syntax()
print(syntax["operators"])
print(syntax["aggregation_functions"])
print(syntax["examples"])

UQL Query Examples

Uptrace uses a SQL-like query language (UQL). You can get comprehensive syntax documentation using client.get_query_syntax(). Here are some examples:

Filter by status

where _status_code = "error"

Filter by service and time

where service_name = "aktar" and _dur_ms > 1000

HTTP errors

where _system = "httpserver" and http_status_code >= 400

Group and aggregate

group by service_name | count() | avg(_dur_ms)

Complex query

where _status_code = "error" and service_name in ("aktar", "gravipay")
| group by service_name, _name
| select service_name, _name, count(), p99(_dur_ms)

Log queries

where _system = "log:all" and log_severity in ("ERROR", "FATAL")
| group by service_name
| select service_name, count()

Metrics queries

metrics:
  - system_cpu_utilization as $cpu
query:
  - avg($cpu) as cpu_avg
  - sum($cpu) by (service_name) as cpu_by_service

Python Client API

The MCP server uses the UptraceClient class internally. You can also use it directly in your Python code:

from datetime import datetime, timedelta
from uptrace_mcp.client import UptraceClient

client = UptraceClient(
    base_url="https://uptrace.xxx",
    project_id="3",
    api_token="your_token"
)

# Query spans
spans = client.get_spans(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    query='where _status_code = "error"',
    limit=100
)

# Query logs
logs = client.query_logs(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    severity="ERROR",
    limit=50
)

# Query metrics
metrics = client.query_metrics(
    time_gte=datetime.utcnow() - timedelta(hours=1),
    time_lt=datetime.utcnow(),
    metrics=["uptrace_tracing_spans as $spans"],
    query=["sum($spans) as total"]
)

# Get query syntax documentation
syntax = client.get_query_syntax()

See examples/query_errors.py for more examples.

Development

Running tests

uv run pytest

Code formatting

uv run black src/
uv run ruff check src/

Type checking

uv run mypy src/

Architecture

uptrace-mcp/
├── src/
│   └── uptrace_mcp/
│       ├── __init__.py
│       ├── server.py      # MCP server with tool handlers
│       ├── client.py      # Uptrace API client
│       └── models.py      # Pydantic data models
├── tests/                 # Test suite
├── pyproject.toml        # Poetry configuration
└── README.md

Troubleshooting

MCP Server Not Found in Cursor

If you see "No server info found" error in Cursor:

1. Verify the configuration file path - Make sure you're editing the correct MCP settings file:

   • 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

2. Check file permissions - Ensure the configuration file is valid JSON and readable

3. Verify uv/Python path - Test the command manually:

   cd /path/to/uptrace-mcp
   uv run uptrace-mcp --help

4. Check environment variables - Make sure all required variables are set in the env section, or a --config string is specified:

   • UPTRACE_URL

   • UPTRACE_PROJECT_ID

   • UPTRACE_API_TOKEN

5. Restart Cursor - After making changes, completely restart Cursor (not just reload)

6. Check Cursor logs - Look for error messages in Cursor's developer console or logs

Connection Issues

If you get connection errors:

1. Verify UPTRACE_URL is correct and includes protocol (https://)

2. Check that UPTRACE_PROJECT_ID is a valid number

3. Ensure UPTRACE_API_TOKEN is valid and not expired

Permission Errors

If you get 403 Forbidden errors:

• Verify the token has access to the specified project

• Check if SSO is enabled (requires separate API user account)

No Data Returned

If queries return no data:

• Check the time range is correct (use UTC timezone)

• Verify spans exist in that time period via Uptrace UI

• Try a broader query without filters first

Testing the Server Manually

1. Check configuration:

   cd /path/to/uptrace-mcp
   python check_config.py

2. Test server startup:

   export UPTRACE_URL="https://uptrace.xxx"
   export UPTRACE_PROJECT_ID="3"
   export UPTRACE_API_TOKEN="your_token"
   uv run uptrace-mcp

   The server should start without errors. Press Ctrl+C to stop it.

3. Verify MCP protocol: The server communicates via stdio, so you won't see output when run directly. If it starts without errors, it's working correctly.

API Documentation

For more information about Uptrace API and UQL syntax, see:

• Uptrace Query Language

• Uptrace API

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.