用途
llm-usage-mcp 用于追踪本地开发中调用多家 LLM 提供商（Anthropic、OpenAI、DeepSeek、Qwen）所产生的 API 费用。它解决多平台账单分散、币种不一、缓存 token 折扣难以理解的问题，让开发者在一个本地位置查看所有调用成本。该工具是成本计量器，不是路由器，不会改变或拦截你的 API 调用，可与路由器或模型排行榜工具并存。
主要能力
- 多提供商支持：Anthropic、OpenAI、DeepSeek、Qwen，均支持流式与非流式调用；DeepSeek 和 Qwen 使用与 Anthropic/OpenAI 相同的捕获路径。
- 本地存储：所有调用记录写入 ~/.llm-usage/usage.db（SQLite），包含 token 数、费用、延迟和用于幂等的 request_id。
- 两种查询方式：通过 MCP 服务器用自然语言向编码智能体提问，或使用 CLI 命令直接查询。
- MCP 工具：七个工具通过 stdio 暴露，包括 query_spend、usage_summary 等，默认排除失败/部分流记录。
- CLI 命令：八个子命令，如 llm-usage spend（按提供商分解本周花费）、llm-usage compare（按 n 输入/m 输出调用比较各模型费用）、llm-usage recommend（根据预算推荐最便宜模型）、llm-usage status（显示数据库、代理、提供商、定价状态）、llm-usage config（显示每个提供商配置）、llm-usage catalog（浏览模型费率）。
- 支持 --json 输出、--color 颜色控制、--provider/--model 过滤标志，以及 --install-completion 安装 shell 补全。
- 定价数据来自 LiteLLM 定价 JSON 的裁剪快照，每周由 GitHub Action 刷新，缺失模型可通过 pricing_overrides.json 本地补充。
- 代理绑定回环地址 127.0.0.1:5525，API 密钥保存在代理端，客户端无需持有密钥。
使用方式
- 安装：通过 PyPI 使用 uv 或 pipx 安装，获得三个控制台脚本：llm-usage（CLI）、llm-usage-mcp（stdio MCP 服务器）、llm-usage-proxy（兼容别名）。或从源码克隆同步。
- 配置 API 密钥：只需为实际使用的提供商设置密钥；缺少密钥的提供商路由返回 503 configuration_error。配置通过环境变量或 .env 文件完成，参考 docs/configuration.md。
- 启动捕获代理：运行代理，它只监听本地回环地址。
- 将编码智能体指向代理：为每个提供商设置对应的 *_BASE_URL 环境变量。例如通过代理启动 Claude Code。
- 确认捕获：通过代理发起调用后，检查 ~/.llm-usage/usage.db 中是否有记录。
- 查询花费：注册 MCP 服务器（如 claude mcp add llm-usage -- llm-usage-mcp），然后在会话中用自然语言提问；或直接在终端运行 CLI 命令。
适用场景
- 使用多家 LLM 提供商进行开发的个人或团队，希望统一查看 API 支出。
- 需要按周、月、年周期（UTC 日历边界）汇总花费，并按提供商或模型分组。
- 在选择模型前，需要比较不同提供商对特定输入/输出 token 量的成本。
- 需要人民币与美元汇率换算，以理解中国模型提供商的账单。
- 注重隐私，不希望数据离开本地或注册 SaaS 服务。
限制
- 当前仅支持 Anthropic、OpenAI、DeepSeek、Qwen 四家提供商，Gemini、Bedrock、Moonshot、Zhipu GLM、MiniMax 等在计划中。
- v1 的 recommend 命令仅按成本排名，--task 参数不影响选择。
- 价格是 LiteLLM 定价 JSON 的定期快照，可能不是实时价格。
- 该工具不改变或路由调用，仅记录通过代理的调用。
- Dockerfile 仅用于自动化 MCP 注册验证，推荐本地使用 uvx llm-usage-mcp 运行。
- 其他功能细节或未来路线图，资料中暂未提供完整信息。
