Skip to main content
Glama
otel-instrumentation-mcp

otel-instrumentation-mcp

by liatrio-labs

---

OpenTelemetry MCP Server

A Model Context Protocol (MCP) server that bridges AI coding assistants (like ClaudeCode, OpenCode, Windsurf, and Cursor) with the OpenTelemetry ecosystem. It provides real-time access to OpenTelemetry repositories, documentation, examples, semantic conventions, and the instrumentation score specification to help engineers implement high-quality observability in their applications.

Why use this?

OpenTelemetry has extensive documentation and many implementation patterns. This MCP server helps AI assistants:

  • Navigate the complexity of OpenTelemetry documentation

  • Provide accurate, up-to-date instrumentation code

  • Follow best practices and semantic conventions

  • Generate instrumentation that scores qualitatively high

  • Avoid common pitfalls and anti-patterns

Related MCP server: Production Monitoring MCP

Features

The MCP server provides tools and prompts to help AI assistants with OpenTelemetry tasks:

  • Repository & Issue Access - Browse OpenTelemetry repositories and search issues

  • Examples & Documentation - Language-specific examples and documentation

  • Semantic Conventions - Access to standardized attribute definitions

  • Instrumentation Scoring - Evaluate telemetry quality based on best practices

  • AI Prompts - Analyze code and generate instrumentation suggestions

Additional capabilities:

  • Self-Instrumented - Full distributed tracing with OpenTelemetry

  • Multi-Transport - Supports stdio (local), HTTP, and SSE protocols

  • Production Ready - Kubernetes manifests, health checks, graceful shutdown

  • GitHub Integration - Authenticated API access via GitHub App or Personal Access Token

Security Notice

Currently supported authentication methods:

  • GitHub Personal Access Token (PAT) - For individual, local use.

  • GitHub App - For hosted deployments.

IMPORTANT: OAuth support is planned for future implementations. Ensure your credentials are properly secured and never commit them to version control.

Quick Start

Prerequisites

  • Python 3.13+

  • uv package manager

  • GitHub authentication (Personal Access Token or GitHub App credentials)

Installation

  1. Clone the repository:

git clone https://github.com/liatrio-labs/otel-instrumentation-mcp.git
cd otel-instrumentation-mcp
  1. Install dependencies:

uv sync
  1. Set up GitHub authentication (choose one):

Option A: Personal Access Token

export GITHUB_TOKEN="github_pat_..."

Option B: GitHub App (recommended for production)

export GITHUB_APP_ID="123456"
export GITHUB_INSTALLATION_ID="654321"
export GITHUB_APP_PRIVATE_KEY_PATH="/path/to/private-key.pem"

NOTE: Additional environment variables can be set, like the OTEL_EXPORTER_OTLP_ENDPOINT. For a list of available environment variables, see .env.examples

  1. Run the MCP server:

uv run otel-instrumentation-mcp

Local Development

For development with hot reload and local Kubernetes:

# Install development dependencies
task install

# Run with Tilt (includes local Kubernetes, OpenTelemetry Collector, hot reload)
tilt up

# Or run development server standalone with hot reload
task dev

# Run tests
task test

# Run linting and formatting
task lint

# Run all checks (test + lint)
task checks

Usage Examples

Configuration with AI Assistants

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "otel-instrumentation-mcp": {
      "command": "uv",
      "args": ["run", "otel-instrumentation-mcp"],
      "cwd": "/path/to/otel-instrumentation-mcp",
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

VS Code

VS Code supports MCP servers through the GitHub Copilot extension (requires Copilot Chat). Add to your workspace's .vscode/mcp.json file:

{
  "servers": {
    "otel-instrumentation-mcp": {
      "command": "uv",
      "args": ["run", "otel-instrumentation-mcp"],
      "cwd": "/path/to/otel-instrumentation-mcp",
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Alternatively, add to your VS Code settings.json for global configuration:

{
  "mcp": {
    "servers": {
      "otel-instrumentation-mcp": {
        "command": "uv",
        "args": ["run", "otel-instrumentation-mcp"],
        "cwd": "/path/to/otel-instrumentation-mcp",
        "env": {
          "GITHUB_TOKEN": "your_github_token"
        }
      }
    }
  }
}

Note: Ensure uv is in your PATH or use the full path to the uv executable. After adding the configuration, reload VS Code and the MCP server should appear in Copilot Chat's available tools.

Windsurf or Cursor

Add to your MCP configuration file:

{
  "mcpServers": {
    "otel-instrumentation-mcp": {
      "command": "uv",
      "args": ["run", "otel-instrumentation-mcp"],
      "cwd": "/path/to/otel-instrumentation-mcp",
      "env": {
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Testing and Development

MCP Inspector

npx @modelcontextprotocol/inspector uv run otel-instrumentation-mcp

Using HTTP/SSE Transports (Remote Access)

For network-accessible deployments:

# HTTP Transport
SERVICE_PORT=8080 uv run otel-instrumentation-mcp
# Access at: http://localhost:8080/mcp/

# SSE Transport
MCP_TRANSPORT=sse MCP_PORT=8080 uv run otel-instrumentation-mcp
# Access at: http://localhost:8080/

Note: Remote access currently requires GitHub authentication configured via environment variables. OAuth support for client authentication is coming soon.

Real-World Example: Instrumenting Your Code

Once configured, you can ask your AI assistant to help with OpenTelemetry instrumentation:

User: Help me add OpenTelemetry instrumentation to my Python Flask application

AI Assistant: I'll help you add OpenTelemetry instrumentation to your Flask
application. Let me first check the latest OpenTelemetry documentation and
examples for Python.

[Uses get_opentelemetry_docs_by_language tool]
[Uses get_opentelemetry_examples_by_language tool]
[Uses get_semantic_conventions tool]

Based on the latest OpenTelemetry documentation, here's how to properly
instrument your Flask application...

[Provides relatively accurate* up-to-date instrumentation code following best
practices]

Production Deployment

Kubernetes

The repository includes Kubernetes manifests with:

  • Deployment with health checks and resource limits

  • Service for internal communication

  • OpenTelemetry Collector integration

  • ConfigMaps for feature flags

  • Support for different environments via the Kustomize overlay pattern (dev, local, prod)

# Example
kubectl apply -k manifests/overlays/prod

Configuration

Environment Variables

Variable

Description

Default

SERVICE_NAME

Service name for telemetry

otel-instrumentation-mcp-server

SERVICE_VERSION

Service version

0.15.0

SERVICE_INSTANCE_ID

Instance identifier

local

SERVICE_PORT

Port for HTTP transport (overrides MCP_PORT)

-

MCP_TRANSPORT

Transport type (stdio, http, sse)

stdio

MCP_HOST

Host binding for HTTP/SSE

Auto-detected

MCP_PORT

Port for HTTP/SSE transport

8080

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP collector endpoint

http://localhost:4317

GitHub Authentication

Choose one authentication method:

GitHub App (Recommended):

  • GITHUB_APP_ID - GitHub App ID

  • GITHUB_INSTALLATION_ID - Installation ID

  • GITHUB_APP_PRIVATE_KEY_PATH - Path to private key

Personal Access Token:

  • GITHUB_TOKEN - GitHub personal access token

Development

Running Tests

# Run all tests
task test

# Run specific test
task test-single -- tests/test_main.py::test_list_opentelemetry_repos_tool

# Run with coverage
task test-coverage

Linting and Formatting

# Run all checks
task checks

# Format code
task lint

Development Server

# Start with hot reload
task dev

# Custom port
SERVICE_PORT=3000 task dev

Observability

The MCP server is fully instrumented with OpenTelemetry, providing:

  • Distributed tracing for MCP operations

  • Custom semantic conventions for MCP and GenAI specific attributes

  • Integration with standard OpenTelemetry collectors

  • High instrumentation quality (measured with Instrumentation Score)

View traces in your preferred backend (Jaeger, Honeycomb, Datadog, Dash0, etc.) by configuring OTEL_EXPORTER_OTLP_ENDPOINT.

Architecture

  • FastMCP Framework - Provides MCP protocol implementation

  • OpenTelemetry SDK - Full observability with auto-instrumentation

  • Async Python - High-performance async/await patterns

  • GitHub GraphQL API - Efficient data fetching from repositories

  • Multi-transport - Flexible deployment options (stdio, HTTP, SSE)

Roadmap

Coming Soon

  • OAuth Support - Full OAuth flow for MCP authentication

  • Caching Layer - Native caching for GitHub API responses to improve performance

  • Weaver Custom Semantic Conventions - Support for custom semantic convention registries through Weaver.

Known Limitations

  • OAuth flow for MCPs isn't implemented yet.

  • GitHub API rate limits apply organizationally when self-hosting through an app.

  • Currently optimized for OpenTelemetry repositories only.

Contributing

We welcome contributions! Please submit issues and pull requests on GitHub. See CONTRIBUTING.md to get started.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

Notice of Attribution

This is a derived worked from @sgsharma's original otel-instrumentation-mcp at this commit.

Available Tools

9 tools
get_instrumentation_score_rulesA

Get Instrumentation Score rules

Returns scoring rules from the Instrumentation Score specification. Rules can be filtered by ID, impact level, or target type.

Args: rule_ids: Comma-separated list of rule IDs to fetch (e.g., "RES-001,SPA-001") impact_levels: Comma-separated list of impact levels (e.g., "Critical,Important") targets: Comma-separated list of targets (e.g., "Resource,Span")

Inputs: rule_ids, impact_levels, targets.

get_instrumentation_score_specA

Get the Instrumentation Score specification

Returns the main specification document for the Instrumentation Score standard, which provides a standardized metric for assessing OpenTelemetry instrumentation quality.

Inputs: no named parameters.

get_opentelemetry_docs_by_languageB

Get OpenTelemetry documentation by language and version

Returns OpenTelemetry documentation for a specific programming language and version

Args: language: Programming language (e.g. python, java, go) version: Version to retrieve (e.g. "v1.2.3", "latest", or None for latest)

Inputs: language, version.

get_opentelemetry_examplesB

Get OpenTelemetry examples

Returns a list of OpenTelemetry demo services and examples

Inputs: no named parameters.

get_opentelemetry_examples_by_languageB

Get OpenTelemetry examples by language

Returns OpenTelemetry examples for a specific programming language

Args: language: Programming language (e.g. python, java, go)

Inputs: language.

get_semantic_conventionsB

Get OpenTelemetry semantic conventions from the semantic-conventions repository

Returns semantic conventions from the OpenTelemetry semantic-conventions repository as markdown documentation files.

Args: category: Optional category filter (e.g., "http", "database", "messaging") count: Maximum number of files to retrieve (default: 50)

Inputs: category, count.

list_opentelemetry_issuesC

Get OpenTelemetry repository issues

Returns issues from a specific OpenTelemetry repository

Args: repo: Repository name (e.g. opentelemetry-python)

Inputs: repo.

list_opentelemetry_reposB

List OpenTelemetry repositories

Returns a list of OpenTelemetry repositories

Inputs: no named parameters.

search_opentelemetry_issuesB

Search OpenTelemetry repository issues

Search for issues in a specific OpenTelemetry repository using keywords

Args: repo: Repository name (e.g. opentelemetry-python) keywords: Keywords to search for in issues

Inputs: repo, keywords.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: rules, spec, docs, examples, semantic conventions, repos, issues, and search. There's no overlap; even the two 'by language' tools differentiate between documentation and examples.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, using clear prefixes like get_, list_, search_. Suffixes like _by_language are applied uniformly, making the naming predictable and easy to navigate.

    Tool Count5/5

    With 9 tools, the server is well-scoped for its purpose as a reference and documentation resource for OpenTelemetry instrumentation. Each tool serves a clear role without being excessive or insufficient.

    Completeness4/5

    The tool set covers essential aspects: rules, spec, docs, examples, conventions, and repository interaction. A minor gap is the lack of a direct tool to compute or evaluate an instrumentation score, but the provided tools offer foundational information for that purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language querying and analysis of OpenTelemetry traces, metrics, and logs stored in Elasticsearch/OpenSearch, allowing AI assistants to investigate performance issues, find root causes, and explore system behavior.
      14
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI agents to live observability stacks including Sentry, GitHub, Vercel, Better Stack, and Cloudflare, enabling end-to-end incident investigation, deployment correlation, root cause analysis, and regression triage.
      14
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to OpenTelemetry trace backends (Jaeger, Grafana Tempo, Traceloop, Datadog, Sentry, AWS X-Ray, New Relic and Honeycomb) for natural-language trace and span search, error triage, cross-backend correlation, and LLM analytics such as token usage, model performance and the most expensive or slowest traces.
      19
      172 PyPI
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to query a local OTLP trace collector: list recent traces, inspect span trees and critical paths, flag SQL N+1 loops, surface gen_ai metrics, and diagnose slow traces with a local OpenAI-compatible model.
      MIT