Let an agent look up its own spend
tokenstat mcp is a Model Context Protocol server. It speaks over stdio, it is
backed by the same local archive as every other command, and it is already in
the binary you installed. There is nothing extra to download.
The point of it is narrow and useful: an agent that can query tokenstat can answer questions about its own work with numbers instead of impressions.
Register it
In Claude Code:
claude mcp add tokenstat -- tokenstat mcp
Any other MCP client takes the same command and arguments in its own config file:
{
"mcpServers": {
"tokenstat": { "command": "tokenstat", "args": ["mcp"] }
}
}
Run tokenstat scan once before you rely on it, or let the hourly schedule the
installer set up do it for you. The server reads the archive; it does not build
it.
What it exposes
Thirty-two tools, in four groups.
| Group | Tools |
|---|---|
| Usage | totals, models, daily, weekly, projects, budget_status, doctor, scan |
| Tasks | task_list, task_create, task_update, task_remove, task_delegate |
| Automations | automation_list, automation_create, automation_update, automation_enable, automation_run, automation_runs, automation_queue, automation_set_queue |
| Workflows | workflow_list, workflow_get, workflow_create, workflow_update, workflow_remove, workflow_run, workflow_runs, workflow_continue, workflow_kill, workflow_transcript, workflow_design |
The usage tools return the same figures the CLI prints. The task tools are the todo board the desktop app shows. Automations are recurring jobs the host daemon owns, each with a budget it stops at rather than one it reports afterwards, and workflows compose agents, automations, shell commands, and a person gate into a graph.
What it will not do
The server reads what is on your machine. It does not reach the network, it does not sync, and it cannot publish anything.
Because it is local, what it returns is the unredacted version: real project
names, real model ids, the same as tokenstat summary in your own terminal.
That is the useful version, and it stays with you. Nothing in this path can
reach a public profile.
Designing a workflow from a prompt produces a draft, never a run. And nothing on a timer writes to git: an automation may run an agent, and that agent may ask a person, but a schedule on its own does not commit.
Related
- The MCP server is the reference version of this page.
- The read API is the hosted equivalent, for pulling your own numbers out of tokenstat.ai as JSON or CSV.
- Which tokenstat command shows what if you would rather ask in a terminal.
More in CLI and MCP