causality-mcp

causality-mcp is a Rust workspace that provides a local MCP server for Claude Desktop plus the ingestion + causal analysis engine behind it.

It is designed for “no-instrumentation” diagnosis: ingest the logs you already have (local files or Docker containers), then ask Claude to explain root cause and causality.

Repository layout

• crates/: Rust workspace crates (reusable libraries + MCP server binary)
• docs/: user-facing guides and copy/paste prompt packs
• docker/test-server/: Docker fixtures and remote-log mirror container recipes
• .github/: CI/release workflows and GitHub templates
• causality.toml: default configuration used by the MCP server

Requirements

• Rust 1.94 (pinned via rust-toolchain.toml)
• Docker Desktop (optional but recommended for container log workflows)

Add to Claude Desktop (2 ways)

You can run the MCP server either by installing from crates.io (recommended for end users) or by running a locally built .exe.

Option 1: Install from crates.io

Install the binary:

cargo install causality-mcp-server

Then configure Claude Desktop to run the installed executable:

{
  "mcpServers": {
    "causality-mcp": {
      "command": "causality-mcp",
      "args": [
        "--config",
        "D:\\\\path\\\\to\\\\causality.toml",
        "--log-level",
        "info"
      ],
      "env": {
        "LOG_CAUSALITY_DOCKER_CMD": "C:\\\\Program Files\\\\Docker\\\\Docker\\\\resources\\\\bin\\\\docker.exe"
      }
    }
  }
}

Option 2: Build and run the .exe

Build from source:

cargo build --release -p causality-mcp-server

Windows output:

• target/release/causality-mcp.exe

Claude Desktop config:

{
  "mcpServers": {
    "causality-mcp": {
      "command": "D:\\\\path\\\\to\\\\target\\\\release\\\\causality-mcp.exe",
      "args": [
        "--config",
        "D:\\\\path\\\\to\\\\causality.toml",
        "--log-level",
        "info"
      ],
      "env": {
        "LOG_CAUSALITY_DOCKER_CMD": "C:\\\\Program Files\\\\Docker\\\\Docker\\\\resources\\\\bin\\\\docker.exe"
      }
    }
  }
}

Restart Claude Desktop after editing claude_desktop_config.json.

MCP tools (current)

The MCP server currently documents Docker-first workflows (direct SSH ingestion prompts are planned / coming soon).

Tools:

• discover_docker_logs
• ingest_logs
  • Local: source glob
  • Docker: docker_container + docker_path
• find_root_cause
• trace_request
• correlate_services
• export_timeline (markdown, csv, html)

Examples

Discover likely log files in a container:

{
  "name": "discover_docker_logs",
  "arguments": {
    "docker_container": "my-container",
    "roots": ["/var/log", "/app/logs", "/logs"],
    "limit": 200
  }
}

Ingest container logs:

{
  "name": "ingest_logs",
  "arguments": {
    "docker_container": "my-container",
    "docker_path": "/var/log/app/*.log",
    "format": "auto"
  }
}

Ingest local file logs:

{
  "name": "ingest_logs",
  "arguments": {
    "source": "D:/logs/myapp/**/*.log",
    "format": "auto"
  }
}

Find root causes:

{
  "name": "find_root_cause",
  "arguments": {
    "error_pattern": "error|exception|panic|failed|timeout|5\\\\d\\\\d",
    "window_secs": 300,
    "max_candidates": 10
  }
}

Export an HTML timeline:

{
  "name": "export_timeline",
  "arguments": {
    "trace_id": "t2",
    "format": "html"
  }
}

Remote server logs (Docker mirror)

If you want to analyze logs on a remote server without running the MCP server on that server, use the Docker “mirror” container:

• docker/test-server/Dockerfile.test2

It connects to your server and mirrors selected log files into /var/log/remote inside the container. You then ingest /var/log/remote/*.log using the Docker tools.

Direct SSH ingestion tools are not documented here (planned / coming soon).

Docs

• Crates overview: crates/README.md
• Prompt kit: docs/CLAUDE_PROMPT_PACK.md
• Skills playbook: docs/SKILLS.md
• Prompt skill suggestions: docs/PROMPT_SKILL_SUGGESTIONS.md
• Docker test server: docker/test-server/HOW_TO_RUN.md