# Opentelemetry Mcp Server

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-traceloop-opentelemetry-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [traceloop](https://agentstack.voostack.com/s/traceloop)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [traceloop](https://github.com/traceloop)
- **Source:** https://github.com/traceloop/opentelemetry-mcp-server

## Install

```sh
agentstack add mcp-traceloop-opentelemetry-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenTelemetry MCP Server

[](https://www.python.org/downloads/)
[](https://pypi.org/project/opentelemetry-mcp/)
[](LICENSE)

**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](#quick-start)
- [Installation](#installation)
- [Features](#features)
- [Configuration](#configuration)
- [Tools Reference](#tools-reference)
- [Example Queries](#example-queries)
- [Common Workflows](#common-workflows)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Support](#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](https://pipx.pypa.io/) or [uv](https://github.com/astral-sh/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](.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 query (1-1000)        |

**Complete `.env` example:**

```bash
# Backend configuration
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

# Optional: API key (mainly for Traceloop)
BACKEND_API_KEY=

# Optional: Request timeout (default: 30s)
BACKEND_TIMEOUT=30

# Optional: Logging level
LOG_LEVEL=INFO

# Optional: Max traces per query (default: 100)
MAX_TRACES_PER_QUERY=100
```

Backend-Specific Setup

### Jaeger

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

### Grafana Tempo

```bash
BACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200
```

### Traceloop

```bash
BACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here
```

> **Note:** The API key contains project information. The backend uses a project slug of `"default"` and Traceloop resolves the actual project/environment from the API key.

---

## Usage

### Quick Start with start_locally.sh (Recommended)

The easiest way to run the server:

```bash
./start_locally.sh
```

This script handles all configuration and starts the server in stdio mode (perfect for Claude Desktop integration). To switch backends, simply edit the script and uncomment your preferred backend.

### Manual Running

For advanced use cases or custom configurations, you can run the server manually.

#### stdio Transport (for Claude Desktop)

Start the MCP server with stdio transport for local/Claude Desktop integration:

```bash
# If installed with pipx/pip
opentelemetry-mcp

# If running from cloned repository with UV
uv run opentelemetry-mcp

# With backend override (pipx/pip)
opentelemetry-mcp --backend jaeger --url http://localhost:16686

# With backend override (UV)
uv run opentelemetry-mcp --backend jaeger --url http://localhost:16686
```

#### HTTP Transport (for Network Access)

Start the MCP server with HTTP/SSE transport for remote access:

```bash
# If installed with pipx/pip
opentelemetry-mcp --transport http

# If running from cloned repository with UV
uv run opentelemetry-mcp --transport http

# Specify custom host and port (pipx/pip)
opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000

# With UV
uv run opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000
```

The HTTP server will be accessible at `http://localhost:8000/sse` by default.

**Transport Use Cases:**

- **stdio transport**: Local use, Claude Desktop integration, single process
- **HTTP transport**: Remote access, multiple clients, network deployment, sample applications

## Tools Reference

### 1. search_traces

Search for traces with flexible filtering:

```python
{
  "service_name": "my-app",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "gen_ai_system": "openai",
  "gen_ai_model": "gpt-4",
  "min_duration_ms": 1000,
  "has_error": false,
  "limit": 50
}
```

**Parameters:**

- `service_name` - Filter by service
- `operation_name` - Filter by operation
- `start_time` / `end_time` - ISO 8601 timestamps
- `min_duration_ms` / `max_duration_ms` - Duration filters
- `gen_ai_system` - LLM provider (openai, anthropic, etc.)
- `gen_ai_model` - Model name (gpt-4, claude-3-opus, etc.)
- `has_error` - Filter by error status
- `tags` - Custom tag filters
- `limit` - Max results (1-1000, default: 100)

**Returns:** List of trace summaries with token counts

### 2. get_trace

Get complete trace details including all spans and OpenLLMetry attributes:

```python
{
  "trace_id": "abc123def456"
}
```

**Returns:** Full trace tree with:

- All spans with attributes
- Parsed OpenLLMetry data for LLM spans
- Token usage per span
- Error information

### 3. get_llm_usage

Get aggregated token usage metrics:

```python
{
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "service_name": "my-app",
  "gen_ai_system": "openai",
  "limit": 1000
}
```

**Returns:** Aggregated metrics with:

- Total promp

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [traceloop](https://github.com/traceloop)
- **Source:** [traceloop/opentelemetry-mcp-server](https://github.com/traceloop/opentelemetry-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-traceloop-opentelemetry-mcp-server
- Seller: https://agentstack.voostack.com/s/traceloop
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.