LocalTrace
GitHub

Start

Quick start

Run LocalTrace with Docker, point your SDKs at localhost, and wire MCP into Cursor or Claude Code.

Docker (recommended)

docker run --rm -p 4318:4318 -p 4317:4317 \
  -v localtrace-data:/app/data \
  ghcr.io/skaznowiecki/localtrace:0.4.0

Open http://localhost:4318. UI, OTLP/HTTP, Sentry, Datadog, and MCP share port 4318. OTLP/gRPC is :4317. Data lives in the localtrace-data volume.

The image is published to GHCR on v* tags (ghcr.io/skaznowiecki/localtrace, public).

Point an SDK at it

OpenTelemetry HTTP

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Sentry

export SENTRY_DSN=http://local@127.0.0.1:4318/1

Datadog

export DD_TRACE_AGENT_URL=http://127.0.0.1:4318

Do not send gRPC to :4318. Use :4317, or keep OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf. See native connectors for the full matrix.

Wire MCP

Agents talk Streamable HTTP at http://127.0.0.1:4318/mcp.

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "localtrace": {
      "url": "http://127.0.0.1:4318/mcp"
    }
  }
}

Claude Code (.mcp.json in the project you are debugging):

{
  "mcpServers": {
    "localtrace": {
      "type": "http",
      "url": "http://127.0.0.1:4318/mcp"
    }
  }
}
npx @modelcontextprotocol/inspector http://127.0.0.1:4318/mcp

Do not attach a raw SQLite MCP. The LocalTrace server is agent-first: compact payloads, since_minutes, and a playbook in server instructions.

Development from source

Requires pnpm, Bun, Node, and Just.

pnpm install
just migrate
just dev

just dev runs the API with bun --hot on apps/api and the web UI via pnpm --filter @localtrace/web dev.

SQLite WAL allows concurrent readers of the live file:

./data/localtrace.db

Wipe the local DB and recreate schema (data is discarded):

just migrate