OpenTelemetry & Docker MCP Server (otel-server)

An intelligent Model Context Protocol (MCP) server that gives autonomous AI agents (like Claude) the ability to act as a Site Reliability Engineer (SRE).

This server bridges the gap between static code analysis and runtime observability. It allows LLMs to autonomously discover Docker containers, monitor resource utilization (OOM risks), tail logs, and drill down into OpenTelemetry distributed traces (via Jaeger), all safely and securely.

Key Features

Built specifically for how LLMs "think" and navigate:

• LLM Context Bounding: All tool outputs are wrapped in strict XML tags (e.g., <container_logs>, <trace_tree>) to prevent the LLM from hallucinating raw logs or trace data as prompt instructions.
• Built-in PII & Credential Redaction: Production logs and traces often contain sensitive data. This server automatically scrubs JWTs, Bearer tokens, emails, credit cards, and password fields before returning data to the LLM (e.g., replacing tokens with [REDACTED_BEARER]).
• Context Window Protection: Hard caps on log tails (max 500 lines) and trace trees (max 200 spans) prevent "wall of text" context window blowouts. Tools include grep_pattern and since/until parameters so the agent can scrub through time iteratively.
• Graceful Degradation: The server catches all API and socket exceptions, returning them as structured text (isError: true) rather than crashing the MCP process, allowing the agent to troubleshoot its own connection issues.

The Tools

This server registers 6 specialized tools with the MCP client:

Installation & Setup

Prerequisites

• Node.js: v22 or higher
• Docker: Running locally (Docker Desktop, OrbStack, or Rancher Desktop)
• Jaeger: (Optional) Running locally or accessible via HTTP API

Build Instructions

# Clone the repository
git clone https://github.com/cruz-andr/otel-server.git
cd otel-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Configuration

The server is configured via environment variables. Copy .env.example to .env or pass them directly through your MCP client.

Connecting to Claude Code

To use this server with Claude Code, run the following command in your terminal:

claude mcp add otel-server -- node /absolute/path/to/otel-server/build/index.js

(Optional) If you need to override the Docker socket path (e.g., for OrbStack users), pass the environment variable:

claude mcp add otel-server --env DOCKER_SOCKET_PATH=unix:///Users/yourname/.orbstack/run/docker.sock -- node /absolute/path/to/otel-server/build/index.js

Usage with Claude Code (Hosted Server)

The easiest way to use otel-server is via the hosted instance on Fly.io, no local build required.

Option 1: CLI command

claude mcp add --transport http otel-server https://otel-server.fly.dev/mcp

Option 2: Project config file

Add a .mcp.json to your project root:

{
  "mcpServers": {
    "otel-server": {
      "type": "http",
      "url": "https://otel-server.fly.dev/mcp"
    }
  }
}

Anyone who clones the repo will auto-connect to the server.

Optional: Add a CLAUDE.md to your project with tool usage instructions so Claude knows when to reach for observability tools. See this repo's CLAUDE.md for an example.

Architecture

This project uses a strict 3-layer architecture to ensure testability and safety:

src/
├── clients/                  # Layer 1: Raw I/O & API interaction
│   ├── docker-client.ts
│   └── jaeger-client.ts
├── tools/                    # Layer 2: MCP protocol schemas → client layer
│   ├── list-containers.ts
│   ├── get-container-status.ts
│   ├── get-container-stats.ts
│   ├── fetch-logs.ts
│   ├── search-error-traces.ts
│   └── get-trace-tree.ts
├── formatters/               # Layer 3: Sanitize, strip & wrap data for LLM ingestion
│   ├── xml-output.ts
│   └── ansi.ts
├── redact.ts                 # PII & credential redaction
├── types/                    # Shared type definitions
│   ├── docker.ts
│   └── jaeger.ts
├── config.ts                 # Environment variable loading
└── index.ts                  # Entry point

Clients (src/clients/) handle all raw I/O and API interaction with Docker and Jaeger.

Tools (src/tools/) connect the MCP protocol schemas to the client layer. Each tool is registered independently with the MCP server.

Formatters (src/formatters/) are pure functions that sanitize, strip, and wrap data for optimal LLM ingestion. The redaction module (src/redact.ts) scrubs PII and credentials from all output.

License

This project is licensed under the MIT License.