MCP server (for agents)
Published as io.github.sriinnu/tokmeter in the MCP registry, shipped in
@sriinnu/tokmeter-mcp. The entry point is the serve subcommand:
{ "command": "npx", "args": ["-y", "@sriinnu/tokmeter-mcp", "serve"] }Claude Code: claude mcp add tokmeter --scope user -- npx -y @sriinnu/tokmeter-mcp serve.
All tools are prefixed tokmeter_. Start with tokmeter_pulse — it answers most
“what am I spending” questions in one call. Full list grouped by purpose:
MCP tool reference.
Every MCP tool is read-only. All 22 declare readOnlyHint: true. An agent
can preview a cleanup with tokmeter_cleanup_preview and list backups with
tokmeter_backups, but deleting and restoring are not available over MCP: the
user runs tokmeter cleanup or tokmeter restore in a terminal, or uses the
TUI. Releases up to 1.19.3 had owner-gated tokmeter_cleanup_execute and
tokmeter_restore tools behind TOKMETER_ENABLE_DESTRUCTIVE_MCP=1; both, and
the variable, are gone. See
Backup & restore.
Daemon HTTP
tokmeter-mcp daemon start runs a warm core so repeated reads never re-scan the
corpus. HTTP listens on 127.0.0.1:9877; WebSocket 9876 accepts live session
registration. Since 1.19.2, both private HTTP reads and WebSocket upgrades
require the owner’s bearer token from ~/.tokmeter/daemon/daemon.token (directory
mode 0700, file mode 0600 on macOS/Linux). /api/ready is the only public
health check. Localhost binding alone does not isolate one OS account from
another. The CLI, statusline and menubar read the token at use time; custom
clients must do the same and must not log it.
| Endpoint | Returns |
|---|---|
/api/ready |
Whether the warm core finished loading |
/api/quick |
Lifetime totals + live signals — cheapest poll |
/api/today |
Today’s totals and per-project split |
/api/summary |
The full TokmeterSummary |
/api/live |
Current bounded live aggregate |
/api/stats, /api/daily, /api/models, /api/providers, /api/projects, /api/sessions |
Scoped aggregates |
/api/statbar-signals |
Burn rate, cache hit, pace, billing window |
/api/quota |
Plan windows per agent (Codex weekly, Claude Code 5h and 7d): used %, reset time, and whether the current pace runs out first |
/api/coverage |
The last week’s coverage reports: session files that changed on a sealed day and fed no usage (1.17.0+) |
/api/rates |
Per-model $/M rates (input, output, cache read/write) with the price source; ?scope=all for every model with usage |
Never run a full scan in a loop. A full corpus scan is memory-heavy; anything polling more than once a minute should read the daemon or the MCP server, which hold warm state.
Something wrong or out of date? This page is generated from its source on GitHub, at the revision this site was checked against.