Token Meter

What whdrnr2583-cmd/token-meter MCP server does

whdrnr2583-cmd/token-meter MCP server turns locally stored Claude Code and Codex activity into queryable usage data. It reads the JSONL history those tools write to disk, stores processed metadata in a local SQLite database, and makes the results available through an MCP interface. The project also includes a dashboard and command-line interface, but the MCP mode is intended for asking an AI client about usage and sessions.

The available data includes token counts, estimated USD-equivalent costs, call counts, models, projects, MCP servers, tools, timestamps, response sizes, and latency measurements. Session results include commands that can be used to resume Claude Code or Codex sessions.

How it works

Run the package locally and start its MCP entry point over stdio. The server reads its existing local database and can rescan the source JSONL logs when requested. The refresh_data tool performs that rescan and returns an updated summary, which is useful after completing new sessions.

The four read-only MCP tools are:

• usage_summary: Reports daily token counts, estimated costs, and call counts by day and model.
• recent_sessions: Lists recent sessions with paste-ready claude --resume or codex resume commands.
• session_tools: Shows tool-level activity within a session, including calls, total tokens, average latency, and response size.
• refresh_data: Scans local logs for new activity and returns a refreshed summary.

Token Meter does not send the source logs to Claude, OpenAI, or another remote service. By default, it stores metadata rather than prompt and response bodies. The database is located at ~/.tokenpulse/usage.db in the current release.

Setup and configuration

Install and register whdrnr2583-cmd/token-meter MCP server with a supported client using the package's MCP installer, or configure the stdio command manually. The direct server command is:

npx -y @whdrnr2583/token-meter mcp

The repository documents setup for Claude Code, Cursor, and Claude Desktop. Its installer can register the server for all supported clients or for an individual client, and it can create backups of existing configuration. Other MCP clients that accept stdio can use the same command.

Before querying data, the package can ingest local history with npx @whdrnr2583/token-meter ingest. The dashboard runs separately with the serve command. No API key, account, proxy, or vendor SDK is required for the local free functionality described in the repository.

Limitations and notes

Cost values are estimates calculated from token counts in local JSONL files and published per-million-token rates. The pricing table is a snapshot, and some categories such as server-side tool use and cache-write variants are approximated. Subscription costs are not represented as invoice charges, so the results should not be used as billing-grade accounting.

The MCP tools are read-only. They report activity already present in local logs and do not provide controls for changing sessions or invoking the tracked tools. Deleting ~/.tokenpulse/ removes the current local database. The README notes that a future release is expected to migrate this directory to ~/.tokenmeter/.

The free tier includes Claude Code and Codex parsing, MCP and tool breakdowns, hourly, model, and project views, seven-day history, and one desktop alert. Paid Pro features add longer history and additional review and alert capabilities, but those features are separate from the core local MCP use described here.