Multi Container Log Correlator

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.

---

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.

Argument	Type	Required	Description
project_name	string	No	Filter by Docker Compose project name. Omit to list all running containers.

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.

Argument	Type	Required	Description
trace_id	string	Yes	The correlation ID to search for e.g. req-998877, a W3C traceparent hex, or an X-Request-ID value.
limit	number	No	Maximum log events to return. Default 200, max 500.

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.

Argument	Type	Required	Description
service_name	string	Yes	Docker container name or Compose service name (e.g. checkout-worker).
limit	number	No	Number of most-recent error lines to return. Default 50, max 500.
include_warnings	boolean	No	Also include WARN-level lines alongside errors. Default false.

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.

Argument	Type	Required	Description
service_name	string	Yes	Docker container name or Compose service name.
limit	number	No	Number of most-recent lines to return. Default 100, max 500.
level_filter	string[]	No	Restrict to specific levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN. Omit for all levels.

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.

Argument	Type	Required	Description
query	string	Yes	Case-insensitive substring to match against log messages (e.g. "connection refused", "NullPointerException").
service_name	string	No	Restrict search to one container. Omit to search all containers simultaneously.
limit	number	No	Maximum matching lines to return. Default 100, max 500.
level_filter	string[]	No	Restrict results to specific log levels.

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.

Argument	Type	Required	Description
service_name	string	No	A specific container to inspect. Omit to get stats for all running containers.

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.

Argument	Type	Required	Description
service_name	string	No	Only list trace IDs seen in this specific service. Omit for all services.
limit	number	No	Maximum number of trace IDs to return. Default 50, max 1000.

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.

Variable	Default	Description
DOCKER_HOST	(auto)	Override with tcp://localhost:2375 for TCP mode (useful on Windows if named pipe access is blocked)
DOCKER_SOCKET_PATH	/var/run/docker.sock	Linux/Mac only override the Unix socket path

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