Name: Opentelemetry Mcp Server.git
Author: traceloop

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

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:

// 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):

{
  "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)

# 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

<details> <summary>Claude Desktop</summary>

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):

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

Using uvx (alternative):

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

For Traceloop backend:

{
  "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"
      }
    }
  }
}

<details> <summary>Using the repository instead of pipx?</summary>

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

Option 1: Wrapper script (easy backend switching)

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

Option 2: UV directly (for multiple backends)

{
  "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"
      }
    }
  }
}

</details> </details> <details> <summary>Claude Code</summary>

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

# 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"

</details> <details> <summary>Codeium (Windsurf)</summary>

Open Windsurf
Navigate to Settings → MCP Servers
Click Add New MCP Server
Add this configuration:

Using pipx (recommended):

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

Using uvx (alternative):

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

<details> <summary>Using the repository instead?</summary>

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

</details> </details> <details> <summary>Cursor</summary>

Open Cursor
Navigate to Settings → MCP
Click Add new MCP Server
Add this configuration:

Using pipx (recommended):

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

Using uvx (alternative):

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

<details> <summary>Using the repository instead of pipx?</summary>

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

</details> </details> <details> <summary>Gemini CLI</summary>

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

Using pipx (recommended):

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

Using uvx (alternative):

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

Then use Gemini CLI with your traces:

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

<details> <parameter name="name">Using the repository instead?</summary>

{
  "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"
      }
    }
  }
}

</details> </details>

Prerequisites:

Python 3.11 or higher
pipx or uv installed

<details> <summary>Optional: Install globally</summary>

If you prefer to install the command globally:

# Install with pipx
pipx install opentelemetry-mcp

# Verify
opentelemetry-mcp --help

# Upgrade
pipx upgrade opentelemetry-mcp

Or with pip:

pip install opentelemetry-mcp

</details>

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:

# 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)

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

Option 2: CLI Arguments (Override environment)

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

<details> <summary>All Configuration

…

Opentelemetry Mcp Server.git

Installation

Configuration

How to use

README