Skip to main content
Glama
ClickHouse Trace-Activity MCP Server

ClickHouse Trace-Activity MCP Server

by Duranta19

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

Tool

What it does

get_trace_activity

Full chronological log timeline for one trace ID — the end-to-end story of a request/user across services.

get_trace_summary

Aggregate view of a trace: total lines, time span, services involved, error count, severity breakdown.

search_logs

Search individual log lines by service, min severity, body text, and time range. Returns their trace IDs to drill into.

find_traces

Discover distinct trace IDs matching filters (e.g. "traces with errors in service X today"), with per-trace counts.

list_services

List distinct ServiceName values with recent log counts.

Related MCP server: Multi-Container Log Correlator MCP Server

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

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:

Client

Scope

File

Claude Code

This project

.mcp.json (project root)

Claude Code

All projects (user)

~/.claude.json (top-level mcpServers key)

Claude Desktop

User

claude_desktop_config.json

Gemini / other

User

e.g. ~/.gemini/config/mcp_config.json

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:

Variable

Default

Purpose

PORT

3003

HTTP port the server listens on

CLICKHOUSE_URL

http://localhost:8123

ClickHouse HTTP endpoint

CLICKHOUSE_USER / CLICKHOUSE_PASSWORD

default / empty

Credentials

CLICKHOUSE_DATABASE

default

Database holding the logs table

CLICKHOUSE_MAX_EXECUTION_TIME

30

Per-query timeout (seconds)

LOGS_TABLE

otel_logs

Logs table name

COL_*

OTel names

Per-column overrides (see .env.example)

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables querying OpenTelemetry logs stored in OpenSearch across development and production environments. Provides tools for searching logs by various criteria including free-text Lucene queries, trace IDs, service names, error levels, and specific fields.
      8
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables debugging of distributed transactions by continuously ingesting Docker container logs, indexing them by trace/request ID, and exposing MCP tools to search, tail, and correlate logs across services.
      7
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables natural-language querying and investigation of homelab logs from syslog, Docker, OTLP, and AI transcripts, with SQLite full-text search, timeline correlation, incident clustering, and fleet topology insights.
      4
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Connects AI assistants to OpenTelemetry trace backends (Jaeger, Grafana Tempo, Traceloop, Datadog, Sentry, AWS X-Ray, New Relic and Honeycomb) for natural-language trace and span search, error triage, cross-backend correlation, and LLM analytics such as token usage, model performance and the most expensive or slowest traces.
      19
      172 PyPI
      1
      Apache 2.0