统一的 MCP 服务器可在多个后端(Jaeger、Tempo、Traceloop 等)中查询 OpenTelemetry 跟踪信息,从而使 AI 代理可以分析分布式跟踪信息
统一的 MCP 服务器可在多个后端(Jaeger、Tempo、Traceloop 等)中查询 OpenTelemetry 跟踪信息,从而使 AI 代理可以分析分布式跟踪信息
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
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"
# 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:16686This approach:
Claude Desktop
Configure the MCP server in your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonUsing 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"
}
}
}
}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)
{
"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"
}
}
}
}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:
# 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)
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"
}
}
}Using the repository instead?
{
"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
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"
}
}
}Using the repository instead of pipx?
{
"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):
{
"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"Using the repository instead?
{
"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:
Optional: Install globally
If you prefer to install the command globally:
# Install with pipx
pipx install opentelemetry-mcp
# Verify
opentelemetry-mcp --help
# Upgrade
pipx upgrade opentelemetry-mcpOr with pip:
pip install opentelemetry-mcp| 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 |
| Feature | Jaeger | Tempo | Traceloop |
|---|---|---|---|
| Search traces | ✓ | ✓ | ✓ |
| Advanced filters | ✓ | ✓ | ✓ |
| Span search | ✓* | ✓ | ✓ |
| Token tracking | ✓ | ✓ | ✓ |
| Error traces | ✓ | ✓ | ✓ |
| LLM tools | ✓ | ✓ | ✓ |
* Jaeger requires service_name parameter for span search
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]"| 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 |
Option 1: Environment Variables (Create .env file - see .env.example)
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686Option 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_KEYConfiguration 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,或尚未同步最近议题。