Token Meter

io.github.whdrnr2583-cmdPublished by GitHub account whdrnr2583-cmdv0.1.17Updated Oct 28, 2026

Local-first dashboard + MCP for Claude Code and Codex token usage. Per-MCP/tool breakdown.

VerifiedSTDIODesktop onlyDeveloper ToolsData & AnalyticsAI & ML

Overview

AI-generated overview

Local-first MCP server that reports Claude Code and Codex token usage and estimated API cost, broken down by day, model, project and MCP tool.

What you can do
  • Summarize daily token counts, USD-equivalent cost and call counts by day and model
  • List recent sessions with paste-ready resume commands
  • Break down a session per tool: call count, tokens, average latency and response size
  • Re-scan local JSONL logs and return a refreshed summary
When to use it
Useful when you want to see what Claude Code or Codex sessions cost, compare a flat-fee plan against equivalent API cost, or find which MCP server or tool consumes the most tokens. Also handy for locating a recent session to resume.
Requirements
Runs locally over stdio via the npm package, typically launched with npx, so Node.js is needed. It reads the JSONL logs Claude Code and Codex already write on disk and stores results in a local SQLite database. No account, API key or environment variable is declared.
Before you install
The JSONL logs it parses contain source code, prompts and tool results, so the local database holds sensitive material even though only metadata is stored by default. Dollar figures are local estimates, not billing-grade numbers. A paid Pro tier is offered separately; the MCP tools themselves are described as read-only.

Installation

In SourceWeft

  1. Open Token Meter in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Token Meter]

Token Meter

Track Claude Code, Codex & Cursor token usage and cost locally — no account, no cloud.

One local dashboard for your Claude Code and Codex token usage. Free, MCP-aware, MIT-licensed core.

npm: @whdrnr2583/token-meter · GitHub: whdrnr2583-cmd/token-meter · Site: token-meter.dev

Token Meter parses the JSONL files that Claude Code and Codex already write to disk and turns them into a real dashboard: cost per project, per model, per MCP tool, per hour. Your data never leaves your machine.

Run your first audit

sh
npx -y @whdrnr2583/token-meter audit

Scans your ingested Claude Code + Codex history for expensive sessions, oversized tool responses, slow tools, repeated calls, and cache waste, ranked by cost and confidence. Runs entirely against your local SQLite database — same local-first, no-cloud processing as the rest of Token Meter. Add --json for machine-readable output; see docs/audit.md for the full flag list and JSON schema.

When to use this

Use Token Meter if you:

  • want to know how many tokens and dollars your Claude Code or Codex sessions are costing — broken down by project, model, and MCP tool
  • are on a flat-fee plan (Claude Max, etc.) and want to see what the equivalent API cost would be
  • want to find which MCP server or tool is eating the most tokens, or which hour of the day is most expensive
  • want to resume a recent session and need the claude --resume / codex resume command handy
  • want all of the above offline, with no account and nothing uploaded

Not a fit if you need billing-grade numbers validated against your Anthropic or OpenAI invoice — Token Meter computes estimates from local JSONL files only.

MCP tools

When Token Meter is wired as an MCP server (install-mcp all), four tools become available to your AI assistant:

ToolWhat it returns
usage_summaryDaily table of token counts, USD-equivalent cost, and call counts — broken down by day and model
recent_sessionsLatest sessions with paste-ready claude --resume / codex resume commands
session_toolsPer-tool breakdown inside a session: call count, total tokens, average latency, response size
refresh_dataRe-scans your local JSONL logs for new activity, then returns a fresh summary

All four are read-only. No data leaves your machine.

Example prompts

Copy-paste any of these into Claude Code or Cursor after installing the MCP server:

Show me my token usage and cost for the last 7 days.
List my recent sessions so I can pick one to resume.
Show the tool breakdown for my most recent session — which tool used the most tokens?
Refresh token-meter data, then tell me which model cost the most this week.
Which hour of the day am I spending the most tokens on?

Quick start

sh
npx @whdrnr2583/token-meter ingest        # scan ~/.claude/projects + ~/.codex/sessionsnpx @whdrnr2583/token-meter stats 30      # CLI summary for last 30 daysnpx @whdrnr2583/token-meter serve         # http://localhost:8765 dashboardnpx @whdrnr2583/token-meter mcp           # run as an MCP server for Claude Code / Cursor

The package is published under an npm scope (@whdrnr2583/) because the bare token-meter name collides with an existing similar name on npm. The CLI binary is still called token-meter after install.

Connect Token Meter to your AI tool (MCP)

One command registers Token Meter with every supported client on your machine:

sh
npx -y @whdrnr2583/token-meter install-mcp all

Handles Claude Code, Cursor, and Claude Desktop — idempotent, backs up existing config, preserves other MCP servers. Single-client variants: install-mcp claude-code | cursor | claude-desktop. Add --dry-run to preview.

Or have your LLM do it. Open Claude Code / Cursor / Claude Desktop and ask: "Read https://raw.githubusercontent.com/whdrnr2583-cmd/token-meter/main/docs/mcp-server.md and set up token-meter as my MCP server."

Manual one-liners (if you'd rather not run our installer):

ClientCommand / config
Claude Codeclaude mcp add token-meter -- npx -y @whdrnr2583/token-meter mcp then claude mcp list to verify
CursorEdit ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) — see docs/mcp-server.md
Claude DesktopEdit claude_desktop_config.json — see docs/mcp-server.md
ChatGPTStdio-only for now; HTTP wrapper recipe in docs/mcp-server.md
Other (Continue, Zed, custom)npx -y @whdrnr2583/token-meter mcp over stdio

Then ask: "Use token-meter to show my recent sessions" or "Use token-meter usage_summary for this week".

Claude Code shortcut: run npx -y @whdrnr2583/token-meter install-command claude-code once to register the /token-meter slash command. After reopening your session, type /token-meter for a one-shot summary without natural language.

Full setup + verification + troubleshooting: docs/mcp-server.md.

Storage: ~/.tokenpulse/usage.db (SQLite). Remove the folder to start over. The folder name will become ~/.tokenmeter/ in a future release with an automatic migration; until then the v0.1 directory keeps its original name.

What you see

  • USD-equivalent cost per day, model, project. Useful if you're on a Max plan and want to know what the API would have cost.
  • MCP and tool breakdown: which MCP server is eating tokens, how slow each tool is on average, response sizes per call.
  • Hourly distribution of output tokens.
  • Claude Code + Codex side-by-side, in one view.

A note on the dollar figures

Costs are estimates computed locally from the token counts that Claude Code and Codex already write to their JSONL files, multiplied by the model's published per-million-token rate. They are not validated against your actual Anthropic / OpenAI invoice and may diverge for several reasons:

  • Vendors change pricing; the table in src/pricing.ts is a snapshot
  • Subscription plans (Pro / Max) bill a flat fee — the on-screen $ is what the API would have cost, not what you pay
  • Some token categories (server-side tool use, cache write variants) are approximated

Treat the numbers as relative signal for spotting waste, not as billing-grade accounting. Token Meter ships a regression test that the calculation is reproducible, and an audit script that checks invariants; neither verifies the rates against vendor invoices.

Why local-first

  • Your JSONL contains source code, prompts, and tool results. Token Meter never uploads any of it. Heuristics, regex, and SQL aggregation only.
  • No SDK to integrate, no proxy to configure for the free tier.
  • The CLI and dashboard core are MIT licensed.

Pricing

TierPriceWhat you get
Free$0Claude Code + Codex parsing, MCP/tool breakdown, hourly/model/project breakdown, 7-day history, 1 desktop alert
Pro$5/moEverything in Free, reframed as a monthly spend review: 30-day history (this month vs last), per-session/per-message drill-down to the run that blew the budget, cache-efficiency dollars saved, waste signals (oversized tool responses + cache that didn't pay off), plus unlimited smart alerts (desktop + webhook)
Pro+laterLocal LLM proxy (Ollama / LM Studio / llama.cpp / vLLM), GPU/VRAM tracking, auto actions

Pro is the difference between glancing at last week's number and reviewing where the month's spend leaked. Pro is live — Subscribe at token-meter.dev.

Pro+ ships once Pro sign-ups + community demand confirm the segment.

Roadmap

  • M1 ✅ Claude Code parsing, MCP/tool breakdown, hourly stats
  • M2 ✅ Codex integration
  • M3 ✅ Pro tier ($5), Polar.sh billing, license activation
  • M4+ Pro+ (local LLM proxy, GPU tracking), conditional on demand

Privacy & security

  • Tokens are counted from the JSONL files Claude Code and Codex already write. Token Meter does not touch network APIs of either vendor.
  • No prompt or response bodies are stored by default — only metadata (timestamps, token counts, tool names, response lengths).
  • The database lives under ~/.tokenpulse/; delete it to wipe. (Renamed to ~/.tokenmeter/ in a future release with an automatic migration.)

Changelog

See CHANGELOG.md for release notes and breaking changes.

License

MIT for the CLI, dashboard, and parsers. Pro-tier features ship in a separate package under a closed source license.

Source: README.md at commit 36c01be

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.17LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts