{"id":34256704,"url":"https://github.com/traceloop/opentelemetry-mcp-server","last_synced_at":"2026-02-28T07:33:15.238Z","repository":{"id":324697190,"uuid":"1088218677","full_name":"traceloop/opentelemetry-mcp-server","owner":"traceloop","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-02T08:47:51.000Z","size":805,"stargazers_count":158,"open_issues_count":11,"forks_count":13,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-02T18:30:01.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/traceloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T14:50:22.000Z","updated_at":"2026-02-02T08:46:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/traceloop/opentelemetry-mcp-server","commit_stats":null,"previous_names":["traceloop/opentelemetry-mcp-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/traceloop/opentelemetry-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traceloop%2Fopentelemetry-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traceloop%2Fopentelemetry-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traceloop%2Fopentelemetry-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traceloop%2Fopentelemetry-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/traceloop","download_url":"https://codeload.github.com/traceloop/opentelemetry-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/traceloop%2Fopentelemetry-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29927582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T19:37:42.220Z","status":"online","status_checked_at":"2026-02-28T02:00:07.010Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-16T14:00:44.458Z","updated_at":"2026-02-28T07:33:15.231Z","avatar_url":"https://github.com/traceloop.png","language":"Python","funding_links":[],"categories":["Developer Tools","Monitoring","📚 Projects (1974 total)","Servers"],"sub_categories":["MCP Servers","Monitoring \u0026 Observability"],"readme":"# OpenTelemetry MCP Server\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/opentelemetry-mcp)](https://pypi.org/project/opentelemetry-mcp/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)\n\n**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.\n\nAn 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.\n\n**See it in action:**\n\nhttps://github.com/user-attachments/assets/e2106ef9-0a58-4ba0-8b2b-e114c0b8b4b9\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Features](#features)\n- [Configuration](#configuration)\n- [Tools Reference](#tools-reference)\n- [Example Queries](#example-queries)\n- [Common Workflows](#common-workflows)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n- [Support](#support)\n\n---\n\n## Quick Start\n\n**No installation required!** Configure your client to run the server directly from PyPI:\n\n```json\n// Add to claude_desktop_config.json:\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\nOr use `uvx` (alternative):\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n**That's it!** Ask Claude: _\"Show me traces with errors from the last hour\"_\n\n---\n\n## Installation\n\n### For End Users (Recommended)\n\n```bash\n# Run without installing (recommended)\npipx run opentelemetry-mcp --backend jaeger --url http://localhost:16686\n\n# Or with uvx\nuvx opentelemetry-mcp --backend jaeger --url http://localhost:16686\n```\n\nThis approach:\n\n- ✅ Always uses the latest version\n- ✅ No global installation needed\n- ✅ Isolated environment automatically\n- ✅ Works on all platforms\n\n### Per Client Integration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\nConfigure the MCP server in your Claude Desktop config file:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**Using pipx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n**Using uvx (alternative):**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n**For Traceloop backend:**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"traceloop\",\n        \"BACKEND_URL\": \"https://api.traceloop.com\",\n        \"BACKEND_API_KEY\": \"your_traceloop_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing the repository instead of pipx?\u003c/summary\u003e\n\nIf you're developing locally with the cloned repository, use one of these configurations:\n\n**Option 1: Wrapper script (easy backend switching)**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"/absolute/path/to/opentelemetry-mcp-server/start_locally.sh\"\n    }\n  }\n}\n```\n\n**Option 2: UV directly (for multiple backends)**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp-jaeger\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/opentelemetry-mcp-server\",\n        \"run\",\n        \"opentelemetry-mcp\"\n      ],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\nClaude Code works with MCP servers configured in your Claude Desktop config. Once configured above, you can use the server with Claude Code CLI:\n\n```bash\n# Verify the server is available\nclaude-code mcp list\n\n# Use Claude Code with access to your OpenTelemetry traces\nclaude-code \"Show me traces with errors from the last hour\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodeium (Windsurf)\u003c/b\u003e\u003c/summary\u003e\n\n1. Open Windsurf\n2. Navigate to **Settings → MCP Servers**\n3. Click **Add New MCP Server**\n4. Add this configuration:\n\n**Using pipx (recommended):**\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"pipx\",\n    \"args\": [\"run\", \"opentelemetry-mcp\"],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n**Using uvx (alternative):**\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"uvx\",\n    \"args\": [\"opentelemetry-mcp\"],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing the repository instead?\u003c/summary\u003e\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"--directory\",\n      \"/absolute/path/to/opentelemetry-mcp-server\",\n      \"run\",\n      \"opentelemetry-mcp\"\n    ],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\n1. Open Cursor\n2. Navigate to **Settings → MCP**\n3. Click **Add new MCP Server**\n4. Add this configuration:\n\n**Using pipx (recommended):**\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"pipx\",\n    \"args\": [\"run\", \"opentelemetry-mcp\"],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n**Using uvx (alternative):**\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"uvx\",\n    \"args\": [\"opentelemetry-mcp\"],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eUsing the repository instead of pipx?\u003c/summary\u003e\n\n```json\n{\n  \"opentelemetry-mcp\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"--directory\",\n      \"/absolute/path/to/opentelemetry-mcp-server\",\n      \"run\",\n      \"opentelemetry-mcp\"\n    ],\n    \"env\": {\n      \"BACKEND_TYPE\": \"jaeger\",\n      \"BACKEND_URL\": \"http://localhost:16686\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/summary\u003e\n\nConfigure the MCP server in your Gemini CLI config file (`~/.gemini/config.json`):\n\n**Using pipx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"pipx\",\n      \"args\": [\"run\", \"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n**Using uvx (alternative):**\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"opentelemetry-mcp\"],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\nThen use Gemini CLI with your traces:\n\n```bash\ngemini \"Analyze token usage for gpt-4 requests today\"\n```\n\n\u003cdetails\u003e\n\u003cparameter name=\"name\"\u003eUsing the repository instead?\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"opentelemetry-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/opentelemetry-mcp-server\",\n        \"run\",\n        \"opentelemetry-mcp\"\n      ],\n      \"env\": {\n        \"BACKEND_TYPE\": \"jaeger\",\n        \"BACKEND_URL\": \"http://localhost:16686\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n**_Prerequisites:_**\n\n- Python 3.11 or higher\n- [pipx](https://pipx.pypa.io/) or [uv](https://github.com/astral-sh/uv) installed\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOptional: Install globally\u003c/b\u003e\u003c/summary\u003e\n\nIf you prefer to install the command globally:\n\n```bash\n# Install with pipx\npipx install opentelemetry-mcp\n\n# Verify\nopentelemetry-mcp --help\n\n# Upgrade\npipx upgrade opentelemetry-mcp\n```\n\nOr with pip:\n\n```bash\npip install opentelemetry-mcp\n```\n\n\u003c/details\u003e\n\n## Features\n\n### Core Capabilities\n\n- **🔌 Multiple Backend Support** - Connect to Jaeger, Grafana Tempo, or Traceloop\n- **🤖 LLM-First Design** - Specialized tools for analyzing AI application traces\n- **🔍 Advanced Filtering** - Generic filter system with powerful operators\n- **📊 Token Analytics** - Track and aggregate LLM token usage across models and services\n- **⚡ Fast \u0026 Type-Safe** - Built with async Python and Pydantic validation\n\n### Tools\n\n| Tool                       | Description                         | Use Case                           |\n| -------------------------- | ----------------------------------- | ---------------------------------- |\n| `search_traces`            | Search traces with advanced filters | Find specific requests or patterns |\n| `search_spans`             | Search individual spans             | Analyze specific operations        |\n| `get_trace`                | Get complete trace details          | Deep-dive into a single trace      |\n| `get_llm_usage`            | Aggregate token usage metrics       | Track costs and usage trends       |\n| `list_services`            | List available services             | Discover what's instrumented       |\n| `find_errors`              | Find traces with errors             | Debug failures quickly             |\n| `list_llm_models`          | Discover models in use              | Track model adoption               |\n| `get_llm_model_stats`      | Get model performance stats         | Compare model efficiency           |\n| `get_llm_expensive_traces` | Find highest token usage            | Optimize costs                     |\n| `get_llm_slow_traces`      | Find slowest operations             | Improve performance                |\n\n### Backend Support Matrix\n\n| Feature          | Jaeger | Tempo | Traceloop |\n| ---------------- | :----: | :---: | :-------: |\n| Search traces    |   ✓    |   ✓   |     ✓     |\n| Advanced filters |   ✓    |   ✓   |     ✓     |\n| Span search      |  ✓\\*   |   ✓   |     ✓     |\n| Token tracking   |   ✓    |   ✓   |     ✓     |\n| Error traces     |   ✓    |   ✓   |     ✓     |\n| LLM tools        |   ✓    |   ✓   |     ✓     |\n\n\u003csub\u003e\\* Jaeger requires `service_name` parameter for span search\u003c/sub\u003e\n\n### For Developers\n\nIf you're contributing to the project or want to make local modifications:\n\n```bash\n# Clone the repository\ngit clone https://github.com/traceloop/opentelemetry-mcp-server.git\ncd opentelemetry-mcp-server\n\n# Install dependencies with UV\nuv sync\n\n# Or install in development mode with editable install\nuv pip install -e \".[dev]\"\n```\n\n---\n\n## Configuration\n\n### Supported Backends\n\n| Backend       | Type        | URL Example                 | Notes                      |\n| ------------- | ----------- | --------------------------- | -------------------------- |\n| **Jaeger**    | Local       | `http://localhost:16686`    | Popular open-source option |\n| **Tempo**     | Local/Cloud | `http://localhost:3200`     | Grafana's trace backend    |\n| **Traceloop** | Cloud       | `https://api.traceloop.com` | Requires API key           |\n\n### Quick Configuration\n\n**Option 1: Environment Variables** (Create `.env` file - see [.env.example](.env.example))\n\n```bash\nBACKEND_TYPE=jaeger\nBACKEND_URL=http://localhost:16686\n```\n\n**Option 2: CLI Arguments** (Override environment)\n\n```bash\nopentelemetry-mcp --backend jaeger --url http://localhost:16686\nopentelemetry-mcp --backend traceloop --url https://api.traceloop.com --api-key YOUR_KEY\n```\n\n\u003e **Configuration Precedence:** CLI arguments \u003e Environment variables \u003e Defaults\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAll Configuration Options\u003c/b\u003e\u003c/summary\u003e\n\n| Variable               | Type    | Default  | Description                                        |\n| ---------------------- | ------- | -------- | -------------------------------------------------- |\n| `BACKEND_TYPE`         | string  | `jaeger` | Backend type: `jaeger`, `tempo`, or `traceloop`    |\n| `BACKEND_URL`          | URL     | -        | Backend API endpoint (required)                    |\n| `BACKEND_API_KEY`      | string  | -        | API key (required for Traceloop)                   |\n| `BACKEND_TIMEOUT`      | integer | `30`     | Request timeout in seconds                         |\n| `LOG_LEVEL`            | string  | `INFO`   | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |\n| `MAX_TRACES_PER_QUERY` | integer | `100`    | Maximum traces to return per query (1-1000)        |\n\n**Complete `.env` example:**\n\n```bash\n# Backend configuration\nBACKEND_TYPE=jaeger\nBACKEND_URL=http://localhost:16686\n\n# Optional: API key (mainly for Traceloop)\nBACKEND_API_KEY=\n\n# Optional: Request timeout (default: 30s)\nBACKEND_TIMEOUT=30\n\n# Optional: Logging level\nLOG_LEVEL=INFO\n\n# Optional: Max traces per query (default: 100)\nMAX_TRACES_PER_QUERY=100\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBackend-Specific Setup\u003c/b\u003e\u003c/summary\u003e\n\n### Jaeger\n\n```bash\nBACKEND_TYPE=jaeger\nBACKEND_URL=http://localhost:16686\n```\n\n### Grafana Tempo\n\n```bash\nBACKEND_TYPE=tempo\nBACKEND_URL=http://localhost:3200\n```\n\n### Traceloop\n\n```bash\nBACKEND_TYPE=traceloop\nBACKEND_URL=https://api.traceloop.com\nBACKEND_API_KEY=your_api_key_here\n```\n\n\u003e **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.\n\n\u003c/details\u003e\n\n---\n\n## Usage\n\n### Quick Start with start_locally.sh (Recommended)\n\nThe easiest way to run the server:\n\n```bash\n./start_locally.sh\n```\n\nThis 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.\n\n### Manual Running\n\nFor advanced use cases or custom configurations, you can run the server manually.\n\n#### stdio Transport (for Claude Desktop)\n\nStart the MCP server with stdio transport for local/Claude Desktop integration:\n\n```bash\n# If installed with pipx/pip\nopentelemetry-mcp\n\n# If running from cloned repository with UV\nuv run opentelemetry-mcp\n\n# With backend override (pipx/pip)\nopentelemetry-mcp --backend jaeger --url http://localhost:16686\n\n# With backend override (UV)\nuv run opentelemetry-mcp --backend jaeger --url http://localhost:16686\n```\n\n#### HTTP Transport (for Network Access)\n\nStart the MCP server with HTTP/SSE transport for remote access:\n\n```bash\n# If installed with pipx/pip\nopentelemetry-mcp --transport http\n\n# If running from cloned repository with UV\nuv run opentelemetry-mcp --transport http\n\n# Specify custom host and port (pipx/pip)\nopentelemetry-mcp --transport http --host 127.0.0.1 --port 9000\n\n# With UV\nuv run opentelemetry-mcp --transport http --host 127.0.0.1 --port 9000\n```\n\nThe HTTP server will be accessible at `http://localhost:8000/sse` by default.\n\n**Transport Use Cases:**\n\n- **stdio transport**: Local use, Claude Desktop integration, single process\n- **HTTP transport**: Remote access, multiple clients, network deployment, sample applications\n\n## Tools Reference\n\n### 1. search_traces\n\nSearch for traces with flexible filtering:\n\n```python\n{\n  \"service_name\": \"my-app\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-01T23:59:59Z\",\n  \"gen_ai_system\": \"openai\",\n  \"gen_ai_model\": \"gpt-4\",\n  \"min_duration_ms\": 1000,\n  \"has_error\": false,\n  \"limit\": 50\n}\n```\n\n**Parameters:**\n\n- `service_name` - Filter by service\n- `operation_name` - Filter by operation\n- `start_time` / `end_time` - ISO 8601 timestamps\n- `min_duration_ms` / `max_duration_ms` - Duration filters\n- `gen_ai_system` - LLM provider (openai, anthropic, etc.)\n- `gen_ai_model` - Model name (gpt-4, claude-3-opus, etc.)\n- `has_error` - Filter by error status\n- `tags` - Custom tag filters\n- `limit` - Max results (1-1000, default: 100)\n\n**Returns:** List of trace summaries with token counts\n\n### 2. get_trace\n\nGet complete trace details including all spans and OpenLLMetry attributes:\n\n```python\n{\n  \"trace_id\": \"abc123def456\"\n}\n```\n\n**Returns:** Full trace tree with:\n\n- All spans with attributes\n- Parsed OpenLLMetry data for LLM spans\n- Token usage per span\n- Error information\n\n### 3. get_llm_usage\n\nGet aggregated token usage metrics:\n\n```python\n{\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-01T23:59:59Z\",\n  \"service_name\": \"my-app\",\n  \"gen_ai_system\": \"openai\",\n  \"limit\": 1000\n}\n```\n\n**Returns:** Aggregated metrics with:\n\n- Total prompt/completion/total tokens\n- Breakdown by model\n- Breakdown by service\n- Request counts\n\n### 4. list_services\n\nList all available services:\n\n```python\n{}\n```\n\n**Returns:** List of service names\n\n### 5. find_errors\n\nFind traces with errors:\n\n```python\n{\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"service_name\": \"my-app\",\n  \"limit\": 50\n}\n```\n\n**Returns:** Error traces with:\n\n- Error messages and types\n- Stack traces (truncated)\n- LLM-specific error info\n- Error span details\n\n## Example Queries\n\n### Find Expensive OpenAI Operations\n\n**Natural Language:** _\"Show me OpenAI traces from the last hour that took longer than 5 seconds\"_\n\n**Tool Call:** `search_traces`\n\n```json\n{\n  \"service_name\": \"my-app\",\n  \"gen_ai_system\": \"openai\",\n  \"min_duration_ms\": 5000,\n  \"start_time\": \"2024-01-15T10:00:00Z\",\n  \"limit\": 20\n}\n```\n\n**Response:**\n\n```json\n{\n  \"traces\": [\n    {\n      \"trace_id\": \"abc123...\",\n      \"service_name\": \"my-app\",\n      \"duration_ms\": 8250,\n      \"total_tokens\": 4523,\n      \"gen_ai_system\": \"openai\",\n      \"gen_ai_model\": \"gpt-4\"\n    }\n  ],\n  \"count\": 1\n}\n```\n\n---\n\n### Analyze Token Usage by Model\n\n**Natural Language:** _\"How many tokens did we use for each model today?\"_\n\n**Tool Call:** `get_llm_usage`\n\n```json\n{\n  \"start_time\": \"2024-01-15T00:00:00Z\",\n  \"end_time\": \"2024-01-15T23:59:59Z\",\n  \"service_name\": \"my-app\"\n}\n```\n\n**Response:**\n\n```json\n{\n  \"summary\": {\n    \"total_tokens\": 125430,\n    \"prompt_tokens\": 82140,\n    \"completion_tokens\": 43290,\n    \"request_count\": 487\n  },\n  \"by_model\": {\n    \"gpt-4\": {\n      \"total_tokens\": 85200,\n      \"request_count\": 156\n    },\n    \"gpt-3.5-turbo\": {\n      \"total_tokens\": 40230,\n      \"request_count\": 331\n    }\n  }\n}\n```\n\n---\n\n### Find Traces with Errors\n\n**Natural Language:** _\"Show me all errors from the last hour\"_\n\n**Tool Call:** `find_errors`\n\n```json\n{\n  \"start_time\": \"2024-01-15T14:00:00Z\",\n  \"service_name\": \"my-app\",\n  \"limit\": 10\n}\n```\n\n**Response:**\n\n```json\n{\n  \"errors\": [\n    {\n      \"trace_id\": \"def456...\",\n      \"service_name\": \"my-app\",\n      \"error_message\": \"RateLimitError: Too many requests\",\n      \"error_type\": \"openai.error.RateLimitError\",\n      \"timestamp\": \"2024-01-15T14:23:15Z\"\n    }\n  ],\n  \"count\": 1\n}\n```\n\n---\n\n### Compare Model Performance\n\n**Natural Language:** _\"What's the performance difference between GPT-4 and Claude?\"_\n\n**Tool Call 1:** `get_llm_model_stats` for gpt-4\n\n```json\n{\n  \"model_name\": \"gpt-4\",\n  \"start_time\": \"2024-01-15T00:00:00Z\"\n}\n```\n\n**Tool Call 2:** `get_llm_model_stats` for claude-3-opus\n\n```json\n{\n  \"model_name\": \"claude-3-opus-20240229\",\n  \"start_time\": \"2024-01-15T00:00:00Z\"\n}\n```\n\n---\n\n### Investigate High Token Usage\n\n**Natural Language:** _\"Which requests used the most tokens today?\"_\n\n**Tool Call:** `get_llm_expensive_traces`\n\n```json\n{\n  \"limit\": 10,\n  \"start_time\": \"2024-01-15T00:00:00Z\",\n  \"min_tokens\": 5000\n}\n```\n\n---\n\n## Common Workflows\n\n### Cost Optimization\n\n1. **Identify expensive operations:**\n\n   ```\n   Use get_llm_expensive_traces to find high-token requests\n   ```\n\n2. **Analyze by model:**\n\n   ```\n   Use get_llm_usage to see which models are costing the most\n   ```\n\n3. **Investigate specific traces:**\n   ```\n   Use get_trace with the trace_id to see exact prompts/responses\n   ```\n\n### Performance Debugging\n\n1. **Find slow operations:**\n\n   ```\n   Use get_llm_slow_traces to identify latency issues\n   ```\n\n2. **Check for errors:**\n\n   ```\n   Use find_errors to see failure patterns\n   ```\n\n3. **Analyze finish reasons:**\n   ```\n   Use get_llm_model_stats to see if responses are being truncated\n   ```\n\n### Model Adoption Tracking\n\n1. **Discover models in use:**\n\n   ```\n   Use list_llm_models to see all models being called\n   ```\n\n2. **Compare model statistics:**\n\n   ```\n   Use get_llm_model_stats for each model to compare performance\n   ```\n\n3. **Identify shadow AI:**\n   ```\n   Look for unexpected models or services in list_llm_models results\n   ```\n\n---\n\n## Development\n\n### Running Tests\n\n```bash\n# With UV\nuv run pytest\n\n# With coverage\nuv run pytest --cov=openllmetry_mcp --cov-report=html\n\n# With pip\npytest\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run ruff format .\n\n# Lint\nuv run ruff check .\n\n# Type checking\nuv run mypy src/\n```\n\n## Troubleshooting\n\n### Backend Connection Issues\n\n```bash\n# Test backend connectivity\ncurl http://localhost:16686/api/services  # Jaeger\ncurl http://localhost:3200/api/search/tags  # Tempo\n```\n\n### Authentication Errors\n\nMake sure your API key is set correctly:\n\n```bash\nexport BACKEND_API_KEY=your_key_here\n# Or use --api-key CLI flag\nopentelemetry-mcp --api-key your_key_here\n```\n\n### No Traces Found\n\n- Check time range (use recent timestamps)\n- Verify service names with `list_services`\n- Check backend has traces: `curl http://localhost:16686/api/services`\n- Try searching without filters first\n\n### Token Usage Shows Zero\n\n- Ensure your traces have OpenLLMetry instrumentation\n- Check that `gen_ai.usage.*` attributes exist in spans\n- Verify with `get_trace` to see raw span attributes\n\n## Future Enhancements\n\n- [ ] Cost calculation with built-in pricing tables\n- [ ] Model performance comparison tools\n- [ ] Prompt pattern analysis\n- [ ] MCP resources for common queries\n- [ ] Caching layer for frequent queries\n- [ ] Support for additional backends (SigNoz, ClickHouse)\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. All tests pass: `pytest`\n2. Code is formatted: `ruff format .`\n3. No linting errors: `ruff check .`\n4. Type checking passes: `mypy src/`\n\n## License\n\nApache 2.0 License - see LICENSE file for details\n\n## Related Projects\n\n- [OpenLLMetry](https://github.com/traceloop/openllmetry) - OpenTelemetry instrumentation for LLMs\n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification\n- [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support\n\n## Support\n\nFor issues and questions:\n\n- GitHub Issues: https://github.com/traceloop/opentelemetry-mcp-server/issues\n- PyPI Package: https://pypi.org/project/opentelemetry-mcp/\n- Traceloop Community: https://traceloop.com/slack\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraceloop%2Fopentelemetry-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftraceloop%2Fopentelemetry-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraceloop%2Fopentelemetry-mcp-server/lists"}