otel-instrumentation-mcp
Allows browsing OpenTelemetry repositories and searching issues via the GitHub API.
Provides access to OpenTelemetry repositories, documentation, examples, semantic conventions, and instrumentation scoring to help implement high-quality observability.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@otel-instrumentation-mcp find the semantic convention for database span attributes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
---
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
Clone the repository:
git clone https://github.com/liatrio-labs/otel-instrumentation-mcp.git
cd otel-instrumentation-mcpInstall dependencies:
uv syncSet 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
Run the MCP server:
uv run otel-instrumentation-mcpLocal 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 checksUsage 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
uvis in your PATH or use the full path to theuvexecutable. 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-mcpUsing 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/prodConfiguration
Environment Variables
Variable | Description | Default |
| Service name for telemetry |
|
| Service version |
|
| Instance identifier |
|
| Port for HTTP transport (overrides MCP_PORT) | - |
| Transport type ( |
|
| Host binding for HTTP/SSE | Auto-detected |
| Port for HTTP/SSE transport |
|
| OTLP collector endpoint |
|
GitHub Authentication
Choose one authentication method:
GitHub App (Recommended):
GITHUB_APP_ID- GitHub App IDGITHUB_INSTALLATION_ID- Installation IDGITHUB_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-coverageLinting and Formatting
# Run all checks
task checks
# Format code
task lintDevelopment Server
# Start with hot reload
task dev
# Custom port
SERVICE_PORT=3000 task devObservability
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
Issues: GitHub Issues
Discussions: GitHub Discussions
Notice of Attribution
This is a derived worked from @sgsharma's original otel-instrumentation-mcp at this commit.
Available Tools
9 toolsget_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
AI code governance and code review for Claude Code, Copilot and Cursor. Checks rules and security.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
AI agent observability for production traces, natural-language insights, and improvement loops.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.14MIT
- AlicenseAqualityBmaintenanceConnects 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.14MIT
- AlicenseAqualityBmaintenanceConnects 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.19172 PyPI1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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