# whdrnr2583-cmd/token-meter [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/whdrnr2583-cmd/token-meter  
**GitHub Stars:** 1  
**npm Downloads (last month):** 346  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/whdrnr2583-cmd-token-meter

## Description
Local-first dashboard + MCP server for Claude Code and Codex token usage. Cost, per-MCP/per-tool breakdown, hourly distribution, and session drill-down — your data never leaves your machine.

## Tools
Capabilities this server exposes over MCP:

- **usage_summary** — Daily table of token counts, USD-equivalent cost, and call counts — broken down by day and model
- **recent_sessions** — Latest sessions with paste-ready `claude --resume` / `codex resume` commands
- **session_tools** — Per-tool breakdown inside a session: call count, total tokens, average latency, response size
- **refresh_data** — Re-scans your local JSONL logs for new activity, then returns a fresh summary

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "token-meter": {
    "command": "npx",
    "args": ["-y","@whdrnr2583/token-meter"]
  }
}
```

## Documentation

## 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:

```sh
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.

_Full upstream README: https://allmcps.com/mcp/whdrnr2583-cmd-token-meter/readme_