zhaoyue722/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:
Prefer to hack on it? Clone and sync from source instead:
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.
Full env-var reference: docs/configuration.md (or copy .env.example to .env and fill in).
3. Run the capture 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:
| Provider | Client env var | Value |
|---|---|---|
| Anthropic | ANTHROPIC_BASE_URL | http://127.0.0.1:5525 |
| OpenAI | OPENAI_BASE_URL | http://127.0.0.1:5525/openai/v1 |