Multi-Container Log Correlator MCP Server

An MCP (Model Context Protocol) server that continuously ingests logs from all running Docker containers, indexes them by trace/request ID, and exposes a clean tools so an LLM can debug distributed transactions without ever switching terminal windows.

How it works

Docker daemon
  Windows  →  //./pipe/docker_engine  (named pipe, auto-detected)
  Linux/Mac →  /var/run/docker.sock   (Unix socket, auto-detected)
  Custom   →  DOCKER_HOST=tcp://...   (TCP via env var)
        │  (multiplexed stdout/stderr streams)
        ▼
  DockerLogWatcher  ──►  LogParser  ──►  TraceIndexedRingBuffer
  (per-container)         (zero-copy         (10 000 lines/container +
   log streams)            parsing)           O(1) trace_id index)
                                                      │
                                                      ▼
                                            MCP stdio transport
                                                      │
                                                      ▼
                                              LLM tool calls

The ring buffer retains the last 10 000 log lines per container. A secondary Map<traceId, Set<slotKey>> index lets search_by_trace_id resolve cross-service timelines in O(1) time regardless of buffer size.

Related MCP server: log-mcp-server

Exposed MCP Tools

The server exposes 7 tools. Use them in the order shown below for a typical debugging session start with topology, narrow to errors, then correlate by trace ID.

1. list_active_containers

Lists all Docker containers currently being monitored by the server.

Use this first to understand the service topology before calling any other tool it tells you the exact service names you will need to pass as arguments.

Returns: Service name, short container ID (12-char), Docker image, running status, and Compose project for each container.

Example:

list_active_containers()
→ api-gateway      (id: a1b2c3d4e5f6, image: nginx:latest,   Up 3 hours)
→ checkout-worker  (id: b2c3d4e5f6a1, image: node:20,        Up 3 hours)
→ inventory-db     (id: c3d4e5f6a1b2, image: postgres:16,    Up 3 hours)

2. search_by_trace_id — Primary debug tool

The core power tool. Takes a trace/request/correlation ID and returns a chronologically merged timeline of every log event across all containers that share that ID resolved in O(1) time using the in-memory trace index.

This is the tool that turns a 500 error into a root cause in seconds. A single call spans every service that touched the request.

Returns: A merged, chronologically sorted list of log lines from all services that logged this trace ID, including the service name, timestamp, log level, and full message for each event.

Example:

search_by_trace_id({ trace_id: "req-998877" })
→ 14:03:21.001  [api-gateway]      INFO   POST /checkout received
→ 14:03:21.045  [checkout-worker]  INFO   Reserving 2x item #42
→ 14:03:22.100  [inventory-db]     ERROR  Deadlock detected on stock_reservations
→ 14:03:22.441  [checkout-worker]  ERROR  DB timeout after 1400ms
→ 14:03:22.443  [api-gateway]      ERROR  Responding 500 to client

3. tail_service_errors

Retrieves the most recent ERROR and FATAL log lines from a specific container. The fastest way to find an initial failure point when you do not yet have a trace ID grab the error, extract its trace ID, then pass it to search_by_trace_id.

Returns: The N most-recent ERROR/FATAL (and optionally WARN) log lines from the named service in chronological order.

Detected levels: FATAL, CRITICAL, ERROR and optionally WARN / WARNING.

Example:

tail_service_errors({ service_name: "checkout-worker", limit: 10, include_warnings: true })
→ 14:03:22.441  ERROR  DB timeout after 1400ms trace_id=req-998877
→ 14:03:19.100  WARN   Slow query detected (980ms) trace_id=req-998800

4. tail_service_logs

Retrieves the N most-recent log lines from a specific container with optional level filtering. Use this to get general context around a service see what it was doing before or after an event without restricting to errors only.

Returns: The most-recent matching log lines in chronological order with timestamp, service name, level, and message.

Example:

tail_service_logs({ service_name: "api-gateway", limit: 50, level_filter: ["INFO", "ERROR"] })
→ Returns the last 50 INFO and ERROR lines from api-gateway

5. search_logs

Case-insensitive full-text search across the buffered log lines of one or all containers. Useful when you know part of an error message but not which service threw it, or when hunting for a specific SQL query, function name, or stack trace snippet that does not carry a trace ID.

Returns: All matching log lines in chronological order annotated with service name, timestamp, and level. Indicates when results are truncated.

Example:

search_logs({ query: "connection refused", limit: 20 })
→ Finds every "connection refused" line across all running containers

6. get_container_stats

Returns buffer statistics for one or all containers at a glance: total lines buffered, error/warn counts, a sample of known trace IDs, and the oldest/newest log timestamps. Useful for a quick system health overview or to verify the buffer is actively filling with live data.

Returns per container:

• Lines buffered (ring buffer holds up to 10,000 lines per container)

• Error count and warning count

• Oldest and newest log timestamps in the buffer

• Sample of known trace IDs seen in that container's logs

Example:

get_container_stats()
→ checkout-worker:  4,821 lines | Errors: 12 | Warnings: 34 | Traces: req-998877, req-998800 …
→ inventory-db:     2,103 lines | Errors: 3  | Warnings: 1  | Traces: req-998877 …
→ api-gateway:      9,441 lines | Errors: 12 | Warnings: 89 | Traces: req-998877, req-998800 …

7. list_trace_ids

Lists all trace/request IDs currently held in the in-memory buffer. Use this when a user reports "something went wrong" with no trace ID browse the available IDs, pick the one closest to the reported time, and feed it directly into search_by_trace_id.

Returns: A numbered list of trace ID strings currently in the buffer.

Example:

list_trace_ids({ service_name: "checkout-worker", limit: 5 })
→ 1. req-998877
→ 2. req-998800
→ 3. req-998741
→ 4. req-998603
→ 5. req-998512

Trace ID Detection

The parser automatically extracts trace identifiers from:

• JSON fields: trace_id, traceId

• W3C traceparent header values embedded in logs

• X-Request-ID, X-Trace-ID, requestid, request_id key-value pairs

• req-XXXXX style short IDs (common in Node.js / Express apps)

• OpenTelemetry trace_id=<hex32> fields

• OpenTelemetry span_id / spanId for span-level correlation

Prerequisites

• Node.js 18+

• Docker running locally (or accessible socket)

• Windows: Docker Desktop running uses //./pipe/docker_engine automatically

• Linux/Mac: Read access to /var/run/docker.sock

Installation & Usage

npm install
node index.js

Environment variables

The server auto-detects the Docker connection for your platform no configuration needed in most cases.

Windows tip: If the server cannot find containers, enable "Expose daemon on tcp://localhost:2375" in Docker Desktop → Settings → General, then set DOCKER_HOST=tcp://localhost:2375 in your MCP config (see below).

Claude Desktop / Cursor config

Add this to your claude_desktop_config.json:

Config file location

• Windows: C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Linux / Mac

{
  "mcpServers": {
    "multi-container-log-correlator-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/multi-container-log-correlator-mcp-server/index.js"]
    }
  }
}

Windows (named pipe works out of the box with Docker Desktop)

{
  "mcpServers": {
    "multi-container-log-correlator-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\multi-container-log-correlator-mcp-server\\index.js"]
    }
  }
}

Windows (TCP fallback if named pipe does not work, enable TCP in Docker Desktop → Settings → General first)

{
  "mcpServers": {
    "multi-container-log-correlator-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\multi-container-log-correlator-mcp-server\\index.js"],
      "env": {
        "DOCKER_HOST": "tcp://localhost:2375"
      }
    }
  }
}

Typical debugging session

User: "The frontend is throwing a 500 error on checkout. Trace ID is req-998877. What happened?"

LLM:
  1. list_active_containers()             → sees api-gateway, checkout-worker, inventory-db
  2. search_by_trace_id("req-998877")     → gets merged timeline across all 3 services
  3. Reads the timeline, spots the DB deadlock in inventory-db at 14:03:22.441
  4. Reports: "inventory-db hit a deadlock on the stock reservation table,
     which caused checkout-worker to time out, propagating a 500 to api-gateway."

Project structure

src/
├── constants.js              # Buffer sizes, regex patterns, socket path
├── services/
│   ├── ringBuffer.js         # TraceIndexedRingBuffer (core data structure)
│   ├── dockerClient.js       # DockerLogWatcher streams from daemon
│   ├── logParser.js          # Stateless line parser (timestamps, levels, trace IDs)
│   └── formatter.js          # Human-readable output helpers
├── schemas/
│   └── toolSchemas.js        # Zod input schemas for every MCP tool
└── tools/
    └── containerTools.js     # All 7 MCP tool registrations
── index.js                  # Entry point wires everything together