LLM Usage

llm-usage-mcp

LLM Usage & Cost Tracker — your local-first spend watchdog

English | 中文

Stop treating your LLM API bills like a scary horror movie you only look at through your fingers at the end of the month. Know what your LLM calls actually cost — across every provider, in one place, on your own machine. Ask your coding agent (MCP) or type a command (CLI).

It's a cost meter, not a router: it tells you what you spent and which provider fits a workload — it never changes your calls. Pairs happily alongside a router or a model-leaderboard tool.

Or straight from the terminal — your week's spend, broken down by provider, and a cross-provider cost comparison before you commit to a model:

Why you'd want this

You're calling LLMs from a handful of providers — Claude, GPT, plus Chinese models like Qwen and DeepSeek. Each one bills in its own dashboard, in its own currency, with its own rules for what a "cached token" costs. So the simplest possible question — *how much am I spending, and on what?* — turns into four browser logins, looking up exchange rates for RMB to USD, and trying to decipher what a "cached context token discount" actually means in midnight math. Most people just cross their fingers and let the bill be a surprise at the end of the month.

llm-usage-mcp captures every call you make into one local store, costs it correctly per provider at the moment it happens, and hands the answer back two ways:

• Ask your coding agent. It's an MCP server, so Claude Code, Cursor, or any MCP client can answer *"how much did I spend on Claude this week?"* or *"which provider is cheapest for a 10k-in / 2k-out call?"* in plain English.
• Or type a command. It's also a CLI — llm-usage spend, llm-usage compare, llm-usage recommend — for when you'd rather not round-trip through an agent.

And it stays out of your way:

• Local-first. No SaaS, no signup, no telemetry. Just a SQLite file at ~/.llm-usage/usage.db. Privacy is a feature, not a setting.
• Multi-provider, Chinese models included. Anthropic, OpenAI, DeepSeek, Qwen — streaming and non-streaming for all four. DeepSeek and Qwen run the same capture path as Anthropic and OpenAI, not a bolted-on afterthought. More providers (Gemini, Bedrock, Moonshot, …) are on the way.

Quickstart

Two minutes from git clone to your first captured call. This part is about capture — getting calls recorded. Reading the data back comes next.

1. Install

Install from PyPI with uv (or pipx) — this puts the three console scripts on your PATH:

uv tool install llm-usage-mcp   # or: pipx install llm-usage-mcp

Prefer to hack on it? Clone and sync from source instead:

git clone https://github.com/zhaoyue722/llm-usage-mcp.git

cd llm-usage-mcp uv sync

Either way you get three console scripts:

• llm-usage — the multi-command CLI. See From the command line (CLI) below.
• llm-usage-mcp — the stdio MCP server.
• llm-usage-proxy — a back-compat alias; identical to llm-usage proxy.

The Quickstart below uses uv run … (the from-source workflow). If you installed from PyPI, the scripts are already on your PATH — drop the uv run prefix, and register the MCP server with claude mcp add llm-usage -- llm-usage-mcp.

2. Set at least one API key

You only need a key for the provider(s) you actually use; the proxy starts regardless and per-route requests return 503 configuration_error for any provider whose key is missing.

export ANTHROPIC_API_KEY=sk-ant-...

and/or:

export OPENAI_API_KEY=sk-... export DEEPSEEK_API_KEY=sk-... export DASHSCOPE_API_KEY=sk-... # Qwen

Full env-var reference: docs/configuration.md (or copy .env.example to .env and fill in).

3. Run the capture proxy

uv run llm-usage-proxy

It binds loopback-only (127.0.0.1:5525) — never reachable from the network. The proxy holds your API keys server-side; clients never need them.

4. Point your coding agent at the proxy

The proxy exposes one route per provider. Set the matching *_BASE_URL env var on the client side:

Example — launch Claude Code with calls routed through the proxy:

ANTHROPIC_BASE_URL=http://127.0.0.1:5525 claude

5. Confirm it's capturing

Make a call through your agent (or any client pointed at the proxy), then check it landed:

uv run llm-usage spend

Every call lands in ~/.llm-usage/usage.db with tokens, cost, latency, and a request_id for idempotency — and shows up in that headline. That's the whole loop: capture on one side, answers on the other.

Querying your spend

Once calls are being captured, you read them back two ways. Same data, same numbers — pick whichever fits the moment.

Ask your coding agent (MCP)

Register the MCP server with Claude Code:

claude mcp add llm-usage -- uv --directory $(pwd) run llm-usage-mcp

Then just ask, in plain English, inside that session:

How much did I spend on Anthropic today? Which provider is cheapest for a 10k-input / 2k-output call?

Claude picks the right tool and reads the numbers back. Seven tools are exposed over stdio; full param/return shapes are in docs/spec.md.

query_spend and usage_summary default to include_failed=false so partial-stream rows don't pollute totals; opt-in via the param.

From the command line (CLI)

The same questions, as a CLI — eight subcommands under one llm-usage console, for when typing is faster than asking your agent.

The examples below assume llm-usage is on your PATH — either source .venv/bin/activate or uv tool install .. Otherwise, prefix each command with uv run (e.g. uv run llm-usage spend).

$ llm-usage

Local-first LLM spend capture + query, exposed over MCP.

Commands proxy Run the local LLM capture proxy on 127.0.0.1. compare Project the cost of a hypothetical workload across every priced model. models Browse the local pricing catalog. recommend Recommend the cheapest priced model for a workload + budget. spend Show recorded spend over a calendar period. status Snapshot of the local install: DB, proxy, providers, pricing. providers List configured providers with key state, wire-format, model count. about Show version, author, license, and the project homepage.

Conventions that hold across every command:

• --json emits the same Pydantic shape the matching MCP tool returns. Pipe straight into jq.
• --color {auto,always,never} honors NO_COLOR and TTY detection. The palette is a warm, low-contrast dark theme — easy on the eyes at 11pm.
• Filter flags (--provider, --model) are case-insensitive on providers, case-sensitive on models, and repeatable where they act as whitelists.
• --version / -V prints the version and exits. --install-completion {bash|zsh|fish|powershell} installs a tab-completion script — one shell restart later, every flag is -able.

compare

Rank every priced model by projected cost for an n-input / m-output call. Cheapest first, percent against the cheapest. Default view family-deduplicates rows that share both a model family root *and* an identical price — so gpt-5-mini and gpt-5-mini-2025-08-07 collapse to one row with ×2. Pass --all to see every catalog row.

# How does an 8k-in / 2k-out call price out today?

$ llm-usage compare --in 8000 --out 2000

Just OpenAI's models:

$ llm-usage compare --in 8000 --out 2000 --model gpt-5-mini --model gpt-5-nano

Same projection, JSON for a script:

$ llm-usage compare --in 8000 --out 2000 --json | jq '.ranked[0]'

models

Catalog browser. Sibling of compare, but answers "what does this model charge?" rather than "what would my workload cost?". Rates per million tokens, sorted alphabetically by provider by default; switch with --sort input or --sort output to find the cheapest in either axis. Cache rates are hidden until you ask (--cache) because most models don't have them and empty columns waste width.

# Full catalog, deduped.

$ llm-usage models

OpenAI's nano models only, with cache rates:

$ llm-usage models --provider openai --match nano --cache

Cheapest input rate first — quick "what's the floor right now?":

$ llm-usage models --sort input

recommend

Picks one. Filters by --provider, --model, and --budget, then returns the cheapest match plus two runner-ups. The reasoning string explains what it