Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
O

opentelemetry-mcp-server

> 编程语言
Open source

Unified MCP server for querying OpenTelemetry traces across multiple backends (Jaeger, Tempo, Traceloop, etc.), enabling AI agents to analyze distributed traces

198 stars0 likes1 views
WebsiteGitHub

About

Unified MCP server for querying OpenTelemetry traces across multiple backends (Jaeger, Tempo, Traceloop, etc.), enabling AI agents to analyze distributed traces

OpenTelemetry MCP Server

Query and analyze LLM traces with AI assistance. Ask Claude to find expensive API calls, debug errors, compare model performance, or track token usage—all from your IDE.

An MCP (Model Context Protocol) server that connects AI assistants to OpenTelemetry trace backends (Jaeger, Tempo, Traceloop), with specialized support for LLM observability through OpenLLMetry semantic conventions.

See it in action:

https://github.com/user-attachments/assets/e2106ef9-0a58-4ba0-8b2b-e114c0b8b4b9


Table of Contents

  • Quick Start
  • Installation
  • Features
  • Configuration
  • Tools Reference
  • Example Queries
  • Common Workflows
  • Troubleshooting
  • Development
  • Support

Quick Start

No installation required! Configure your client to run the server directly from PyPI:

json
// Add to claude_desktop_config.json:
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Or use uvx (alternative):

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

That's it! Ask Claude: "Show me traces with errors from the last hour"


Installation

For End Users (Recommended)

bash
# Run without installing (recommended)
pipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686

# Or with uvx
uvx opentelemetry-mcp --backend jaeger --url http://localhost:16686

This approach:

  • ✅ Always uses the latest version
  • ✅ No global installation needed
  • ✅ Isolated environment automatically
  • ✅ Works on all platforms

Per Client Integration

Claude Desktop

Configure the MCP server in your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Using pipx (recommended):

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Using uvx (alternative):

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

For Traceloop backend:

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "traceloop",
        "BACKEND_URL": "https://api.traceloop.com",
        "BACKEND_API_KEY": "your_traceloop_api_key_here"
      }
    }
  }
}

Using the repository instead of pipx?

If you're developing locally with the cloned repository, use one of these configurations:

Option 1: Wrapper script (easy backend switching)

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "/absolute/path/to/opentelemetry-mcp-server/start_locally.sh"
    }
  }
}

Option 2: UV directly (for multiple backends)

json
{
  "mcpServers": {
    "opentelemetry-mcp-jaeger": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/opentelemetry-mcp-server",
        "run",
        "opentelemetry-mcp"
      ],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Claude Code

Claude Code works with MCP servers configured in your Claude Desktop config. Once configured above, you can use the server with Claude Code CLI:

bash
# Verify the server is available
claude-code mcp list

# Use Claude Code with access to your OpenTelemetry traces
claude-code "Show me traces with errors from the last hour"

Codeium (Windsurf)

  1. Open Windsurf
  2. Navigate to Settings → MCP Servers
  3. Click Add New MCP Server
  4. Add this configuration:

Using pipx (recommended):

json
{
  "opentelemetry-mcp": {
    "command": "pipx",
    "args": ["run", "opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Using uvx (alternative):

json
{
  "opentelemetry-mcp": {
    "command": "uvx",
    "args": ["opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Using the repository instead?

json
{
  "opentelemetry-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/opentelemetry-mcp-server",
      "run",
      "opentelemetry-mcp"
    ],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Cursor

  1. Open Cursor
  2. Navigate to Settings → MCP
  3. Click Add new MCP Server
  4. Add this configuration:

Using pipx (recommended):

json
{
  "opentelemetry-mcp": {
    "command": "pipx",
    "args": ["run", "opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Using uvx (alternative):

json
{
  "opentelemetry-mcp": {
    "command": "uvx",
    "args": ["opentelemetry-mcp"],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Using the repository instead of pipx?

json
{
  "opentelemetry-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/absolute/path/to/opentelemetry-mcp-server",
      "run",
      "opentelemetry-mcp"
    ],
    "env": {
      "BACKEND_TYPE": "jaeger",
      "BACKEND_URL": "http://localhost:16686"
    }
  }
}

Gemini CLI

Configure the MCP server in your Gemini CLI config file (~/.gemini/config.json):

Using pipx (recommended):

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "pipx",
      "args": ["run", "opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Using uvx (alternative):

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uvx",
      "args": ["opentelemetry-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Then use Gemini CLI with your traces:

bash
gemini "Analyze token usage for gpt-4 requests today"

Using the repository instead?

json
{
  "mcpServers": {
    "opentelemetry-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/opentelemetry-mcp-server",
        "run",
        "opentelemetry-mcp"
      ],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

Prerequisites:

  • Python 3.11 or higher
  • pipx or uv installed

Optional: Install globally

If you prefer to install the command globally:

bash
# Install with pipx
pipx install opentelemetry-mcp

# Verify
opentelemetry-mcp --help

# Upgrade
pipx upgrade opentelemetry-mcp

Or with pip:

bash
pip install opentelemetry-mcp

Features

Core Capabilities

  • ** Multiple Backend Support** - Connect to Jaeger, Grafana Tempo, or Traceloop
  • ** LLM-First Design** - Specialized tools for analyzing AI application traces
  • ** Advanced Filtering** - Generic filter system with powerful operators
  • ** Token Analytics** - Track and aggregate LLM token usage across models and services
  • ⚡ Fast & Type-Safe - Built with async Python and Pydantic validation

Tools

Tool Description Use Case
search_traces Search traces with advanced filters Find specific requests or patterns
search_spans Search individual spans Analyze specific operations
get_trace Get complete trace details Deep-dive into a single trace
get_llm_usage Aggregate token usage metrics Track costs and usage trends
list_services List available services Discover what's instrumented
find_errors Find traces with errors Debug failures quickly
list_llm_models Discover models in use Track model adoption
get_llm_model_stats Get model performance stats Compare model efficiency
get_llm_expensive_traces Find highest token usage Optimize costs
get_llm_slow_traces Find slowest operations Improve performance

Backend Support Matrix

Feature Jaeger Tempo Traceloop
Search traces ✓ ✓ ✓
Advanced filters ✓ ✓ ✓
Span search ✓* ✓ ✓
Token tracking ✓ ✓ ✓
Error traces ✓ ✓ ✓
LLM tools ✓ ✓ ✓

* Jaeger requires service_name parameter for span search

For Developers

If you're contributing to the project or want to make local modifications:

bash
# Clone the repository
git clone https://github.com/traceloop/opentelemetry-mcp-server.git
cd opentelemetry-mcp-server

# Install dependencies with UV
uv sync

# Or install in development mode with editable install
uv pip install -e ".[dev]"

Configuration

Supported Backends

Backend Type URL Example Notes
Jaeger Local http://localhost:16686 Popular open-source option
Tempo Local/Cloud http://localhost:3200 Grafana's trace backend
Traceloop Cloud https://api.traceloop.com Requires API key

Quick Configuration

Option 1: Environment Variables (Create .env file - see .env.example)

bash
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

Option 2: CLI Arguments (Override environment)

bash
opentelemetry-mcp --backend jaeger --url http://localhost:16686
opentelemetry-mcp --backend traceloop --url https://api.traceloop.com --api-key YOUR_KEY

Configuration Precedence: CLI arguments > Environment variables > Defaults

All Configuration Options

Variable Type Default Description
BACKEND_TYPE string jaeger Backend type: jaeger, tempo, or traceloop
BACKEND_URL URL - Backend API endpoint (required)
BACKEND_API_KEY string - API key (required for Traceloop)
BACKEND_TIMEOUT integer 30 Request timeout in seconds
LOG_LEVEL string INFO Logging level: DEBUG, INFO, WARNING, ERROR
MAX_TRACES_PER_QUERY integer 100 Maximum traces to return per

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Python

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言