ClickHouse Trace-Activity MCP Server

A custom Model Context Protocol server that lets an MCP client (Claude Desktop, Claude Code, etc.) track a user's activity by trace ID from application logs stored in ClickHouse.

It exposes the modern Streamable HTTP transport, so it runs as an always-on service in Docker — start it once and it stays up (auto-restarting on crash or reboot) until you stop it.

Tools

Log schema

Defaults to the OpenTelemetry logs schema (table otel_logs):

Timestamp, SeverityText, SeverityNumber, Body, ServiceName, TraceId, SpanId, ResourceAttributes, LogAttributes

Every column name and the table name are overridable via environment variables (see .env.example) — no code changes needed if your table differs.

Quick start (Docker)

cp .env.example .env          # set CLICKHOUSE_URL etc.
docker compose up -d --build  # build + run, detached

The server is now at http://localhost:3003/mcp and will restart automatically until you run:

docker compose down           # stop it

Useful:

docker compose logs -f        # follow logs
curl localhost:3003/health    # health + ClickHouse connectivity check

Connecting to a ClickHouse on your host machine

From inside the container, localhost is the container itself. Use host.docker.internal to reach a ClickHouse running on your Mac/Windows host:

CLICKHOUSE_URL=http://host.docker.internal:8123

If ClickHouse runs in another Docker network, point CLICKHOUSE_URL at that service name and attach this server to the same network.

Connecting an MCP client

Point your client at the Streamable HTTP endpoint:

http://localhost:3003/mcp

JSON config (recommended)

Most MCP clients use a JSON config file. Add this trace-activity entry under mcpServers:

{
  "mcpServers": {
    "trace-activity": {
      "type": "http",
      "url": "http://localhost:3003/mcp"
    }
  }
}

Where to put it:

After editing, reload/restart the client. In Claude Code, run /mcp to confirm trace-activity shows connected with its 5 tools.

Some clients use "transport": "streamable-http" instead of "type": "http". If type isn't recognized, try that key.

CLI alternative (Claude Code)

claude mcp add --transport http trace-activity http://localhost:3003/mcp
# or for all projects:
claude mcp add --scope user --transport http trace-activity http://localhost:3003/mcp

Skip the per-call permission prompt (optional)

To let the tools run without prompting each time, add to your Claude Code settings (.claude/settings.json for this project, or ~/.claude/settings.json for all projects):

{
  "permissions": {
    "allow": ["mcp__trace-activity__*"]
  }
}

Local development (without Docker)

nvm use 22
npm install
npm run dev      # tsx watch, hot reload
# or
npm run build && npm start

Configuration

All settings come from environment variables; see .env.example. Key ones:

Notes

• All tool inputs are bound as ClickHouse server-side query parameters, so

arguments can't be used for SQL injection.

• The server runs as the non-root node user inside the container.
• docker stop / docker compose down sends SIGTERM; the server drains MCP

sessions and closes the ClickHouse client gracefully.