Llm Usage & Cost Tracker

MCP开发工具

提供方 zhaoyue722

开发工具 未标注 API Key 社区 / 第三方 ClaudeCursorGemini CLICodex
查看接入方式

A local-first, multi-provider cost meter for LLM usage, exposed as MCP tools. Captures every call into a local SQLite ledger and lets any coding agent query spend, compare providers, and get recommendations — no cloud, no account. First-class support for Chinese providers (Qwen,

一句话选型结论

按资料字段整理

Llm Usage & Cost Tracker 属于开发工具类 MCP 服务器,传输方式未标注,API Key,可直接接入 Claude、Cursor、Gemini CLI 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式未标注 鉴权API Key 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

cost trackingllmobservability

安装与配置

未标注 API Key
上游未给出传输方式
"command": "uvx",\r

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、Gemini CLI,换客户端不用重新研究配置。

先想清楚的地方

  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Llm Usage & Cost Tracker当前 未标注 未标注 未标注 有 未标注
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方zhaoyue722上游标注的维护方 zhaoyue722
分类开发工具本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · python本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

13.9 KB
来自项目仓库与上游目录的原文,未做删改

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:```bash
uv tool install llm-usage-mcp # or: pipx install llm-usage-mcp


Prefer to hack on it? Clone and sync from source instead:```bash
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.```bash
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```bash
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:

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
DeepSeek DEEPSEEK_BASE_URL (or any OpenAI-SDK base-url override) http://127.0.0.1:5525/deepseek/v1
Qwen DashScope OpenAI-compatible base http://127.0.0.1:5525/qwen/v1

Example — launch Claude Code with calls routed through the proxy:```bash
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:```bash
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:```bash
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`.

| Tool | Purpose |
|---|---|
| `query_spend` | Totals + per-group rollups over a time window (group by provider / model / project / tag / day). |
| `usage_summary` | Headline summary for `today` / `week` / `month` / `year` — totals, top-N providers + models, largest call. |
| `compare_providers` | Given a hypothetical workload (tokens in / out), rank every priced model by cost. |
| `recommend_provider` | Pick the cheapest priced model that fits a stated budget. |
| `get_pricing` | Inspect the vendored pricing snapshot. |
| `list_providers` | List providers + their models + OpenAI-compatibility flag. |
| `record_usage` | Manual write path — log a call when the capture proxy isn't in the picture. |

`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`).```text
$ 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.
Command The question it answers
compare Given a workload, who's cheapest?
models What do they actually charge per million tokens?
recommend I've got $0.04 left — which model won't bankrupt me?
spend How much did I just spend?
status Is everything actually working?
providers What's configured locally?
about What is this, and where do I report a bug?
proxy Run the capture proxy (same as llm-usage-proxy).

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

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.```bash
# 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 assumed and what got chosen, so you can sanity-check rather than trust blindly.```bash

Cheapest priced model, full stop.

$ llm-usage recommend

Anything Anthropic that fits under one cent for a 1k/1k call:

$ llm-usage recommend --provider anthropic --budget 0.01

Of these three specific candidates, which wins?

$ llm-usage recommend --model gpt-5-mini --model claude-sonnet-4-6 --model qwen-max


v1 ranks by cost only. `--task` is optional and surfaces in the reasoning text; it doesn't drive selection (the tool isn't an LLM and can't interpret free text).

#### `spend`

Read the SQLite. The default view is a `usage_summary` headline — total dollars, top-3 providers, top-3 models, largest single call. Pass `--group-by` to switch into rollup mode.```bash
# Headline for this week.
$ llm-usage spend

# This month grouped by model, JSON for a dashboard:
$ llm-usage spend --period month --group-by model --json | jq

# Spend on a specific project tag, day-by-day:
$ llm-usage spend --group-by day --project my-side-thing

Period boundaries are calendar UTC: today = since 00:00 UTC, week = since Monday, month = since the 1st, year = since January 1st. Failed / partial-stream rows are excluded by default; opt in with --include-failed.

status

One screen, four sections: Database, Capture proxy, Providers, Pricing. The "is everything actually working?" command. Read-only — running it on a fresh install before you've ever booted the proxy or MCP server prints database not initialized rather than silently creating the file.```bash
$ llm-usage status

Skip the network probe (offline, CI, slow link):

$ llm-usage status --no-net

Machine-readable for a healthcheck script:

$ llm-usage status --json


#### `providers`

Per-provider configuration view. Wider than the `status` Providers block: adds the wire-format flag (`openai-compat: yes/no`) and an optional `--models` expansion that lists every priced model under each provider.```bash
$ llm-usage providers
$ llm-usage providers --models   # expand each provider with its model list

about

The front-door panel: version, author, license, and the project homepage. The human-facing companion to --version — fields are read from the installed package metadata, so they match what PyPI shows.```bash
$ llm-usage about

Machine-readable, for a script or an issue template:

$ llm-usage about --json
```

Supported providers

Provider Auth Non-streaming Streaming Cache pricing
Anthropic x-api-key yes yes cache_creation + cache_read
OpenAI Bearer yes yes nested prompt_tokens_details.cached_tokens
DeepSeek Bearer yes yes prompt_cache_hit_tokens / _miss_tokens
Qwen (DashScope) Bearer yes yes usually omitted on the OpenAI-compat endpoint

More on the way. Google Gemini, AWS Bedrock, Moonshot (Kimi), Zhipu GLM, MiniMax, and others are scoped in docs/post_v1_providers.md.

Where prices come from. Pricing is a vendored, trimmed snapshot of LiteLLM's pricing JSON, refreshed weekly by a GitHub Action (refresh-pricing.yml). Models LiteLLM doesn't carry yet are filled in locally via pricing_overrides.json.

Configuration

Everything is env vars (or a .env file at the repo root). Defaults are sane — nothing is required to start the proxy. Full reference: docs/configuration.md. The three you're most likely to touch:

Variable Default Purpose
LLM_USAGE_DB_URL sqlite:///$HOME/.llm-usage/usage.db Where the local DB lives.
LLM_USAGE_PROXY_PORT 5525 Capture proxy port (loopback only).
LLM_USAGE__BASE_URL each provider's official endpoint Point a provider at a reverse proxy / gateway — handy in network-restricted regions.

Docker

A minimal Dockerfile is included only for automated MCP registry validation (e.g. Glama), which verifies that the packaged server boots and responds to MCP introspection. The recommended way to run the server is still uvx llm-usage-mcp locally — this is a local-first tool, not a hosted service.

License

MIT.

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Llm Usage & Cost Tracker 怎么安装?

在客户端按下面的安装命令接入:"command": "uvx",\r。装完在客户端配置里引用同一个包或端点。

Llm Usage & Cost Tracker 怎么在 Claude、Cursor、Gemini CLI 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Llm Usage & Cost Tracker 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Llm Usage & Cost Tracker 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Llm Usage & Cost Tracker 支持哪些客户端?

资料标注支持 Claude、Cursor、Gemini CLI、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Llm Usage & Cost Tracker 能提供哪些能力?

资料显示能力标签包括 cost tracking、llm、observability、pricing、local first、anthropic。具体工具清单以官方文档为准。

Llm Usage & Cost Tracker 需要什么运行环境?

运行时为 python。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。