Otel Instrumentation Mcp

---

---

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

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](./.env.example)

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](./CONTRIBUTING.md) to get started.

License

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

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Notice of Attribution

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

[otel-instrumentation-mcp]: https://github.com/sgsharma/otel-instrumentation-mcp [cmt]: https://github.com/sgsharma/otel-instrumentation-mcp/commit/0cea25dd127a403bf3a8e29e1645cc606bf64b66

Source & license

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

• Author: liatrio-labs
• Source: liatrio-labs/otel-instrumentation-mcp
• License: Apache-2.0

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