ClickHouse Trace-Activity MCP Server
Provides tools to query and analyze application logs stored in ClickHouse, enabling tracking of user activity by trace ID across services.
Supports the OpenTelemetry log schema by default, allowing trace activity tracking and log analysis from OpenTelemetry-formatted logs in ClickHouse.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Full chronological log timeline for one trace ID — the end-to-end story of a request/user across services. |
| Aggregate view of a trace: total lines, time span, services involved, error count, severity breakdown. |
| Search individual log lines by service, min severity, body text, and time range. Returns their trace IDs to drill into. |
| Discover distinct trace IDs matching filters (e.g. "traces with errors in service X today"), with per-trace counts. |
| List distinct |
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, detachedThe server is now at http://localhost:3003/mcp and will restart automatically
until you run:
docker compose down # stop itUseful:
docker compose logs -f # follow logs
curl localhost:3003/health # health + ClickHouse connectivity checkConnecting 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:8123If 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/mcpJSON 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:
Client | Scope | File |
Claude Code | This project |
|
Claude Code | All projects (user) |
|
Claude Desktop | User |
|
Gemini / other | User | e.g. |
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". Iftypeisn'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/mcpSkip 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 startConfiguration
All settings come from environment variables; see .env.example. Key ones:
Variable | Default | Purpose |
|
| HTTP port the server listens on |
|
| ClickHouse HTTP endpoint |
|
| Credentials |
|
| Database holding the logs table |
|
| Per-query timeout (seconds) |
|
| Logs table name |
| OTel names | Per-column overrides (see |
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
nodeuser inside the container.docker stop/docker compose downsendsSIGTERM; 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Read-only plain-English activity log of your Rails or Next.js app: actions, actors, failures.
Search your mobile, web and server app logs session by session, and read grouped errors, daily stats, releases and alerts.
Read-only access to Auralogs production logs: search logs, inspect errors, review AI analyses.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables 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-
- AlicenseAqualityDmaintenanceEnables 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.7ISC
- AlicenseNot gradedqualityBmaintenanceEnables 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.4AGPL 3.0
- AlicenseAqualityBmaintenanceConnects 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.19172 PyPI1Apache 2.0