CLI reference

`clawmetry mcp`#

Start the ClawMetry MCP server on stdio, so an agent can query its own telemetry.

bash

clawmetry mcp

No flags. The server speaks newline-delimited JSON-RPC 2.0 over stdin and stdout, implementing MCP 2024-11-05. It is meant to be launched by an MCP client, not run by hand — though running it by hand is a perfectly good way to check it works.

What it exposes#

Five tools:

Tool	Answers
`list_sessions`	What have I been running?
`get_cost_summary`	What did it cost over this window?
`get_session_trace`	What happened inside one session?
`list_events`	Raw events, filtered by session, type or time
`get_health`	Is the ClawMetry daemon itself healthy?

Full argument reference: MCP tool reference.

Registering it#

Claude Code

claude mcp add clawmetry -- clawmetry mcp

Any MCP client, by config

{
  "mcpServers": {
    "clawmetry": {
      "command": "clawmetry",
      "args": ["mcp"]
    }
  }
}

More clients, and the per-client paths: Connect the MCP server.

How it reads data#

The server does not open DuckDB. It reads the daemon's discovery file at ~/.clawmetry/local_query.json, checks the recorded pid is actually alive, and posts queries to the daemon's localhost query server with the bearer token from that file.

That has three consequences worth knowing:

The daemon must be running. With no daemon, every tool returns

{"error": "ClawMetry daemon is not running. Start it with: clawmetry sync"} rather than an empty result that looks like "you did nothing this week".

No lock contention. The MCP server never competes with the daemon for the

writer lock, so an agent hammering it cannot slow ingest.

It is local. The transport is loopback with a token. Nothing about MCP

opens a network surface.

Checking it by hand#

bash

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | clawmetry mcp

You should get a JSON-RPC response listing the five tools. If you get the daemon-not-running error instead, start the daemon first.

Why this exists#

An agent that can read its own history can answer questions no external dashboard can, because it knows what it was trying to do. "Have I hit this error before?" and "am I repeating a session that already failed?" are cheap questions with the history and impossible without it.

The recipes are in Self-diagnosis.

Edit this page View as Markdown Report an issue

clawmetry mcp#