# zhaoyue722/llm-usage-mcp [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/zhaoyue722/llm-usage-mcp  
**GitHub Stars:** 3  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zhaoyue722-llm-usage-mcp

## Description
Local-first LLM API cost tracker. Captures usage across Anthropic, OpenAI, Qwen, and DeepSeek into a local SQLite ledger and exposes spend queries, provider comparison, and recommendations as MCP tools — with first-class Chinese-provider support (CNY→USD). Install: uvx llm-usage-mcp.

## Tools
Capabilities this server exposes over MCP:

- **record_usage** — Record a single LLM API call with token counts.

Cost is computed automatically from the pricing table at insert time.
`request_id` enables idempotent recording — replaying a log file
won't double-count.

- **query_spend** — Return spending broken down by a chosen axis over a time window.

`start` and `end` are ISO-8601 strings (trailing-`Z`, `+00:00`, or
naive — naive is interpreted as UTC). Default window is the last
30 days. `group_by` is one of provider | model | project | tag | day.
`filter` AND-combines optional provider/model/project equality
predicates.

`include_failed` defaults to `False` so failure rows (e.g. streams
that died mid-flight with partial counts) are excluded from totals
and groups. Pass `True` to fold them back in — useful for debugging
capture-layer behavior, not for honest spend numbers.

Tag semantics: events with NULL/empty tags are excluded from
`group_by="tag"` results entirely; multi-tag events contribute once
per tag (so per-group `calls` sums can exceed the window total).
Project semantics are symmetric: NULL projects are dropped from
`group_by="project"`. Groups are ordered cost-desc with
alphabetical ties.

- **compare_providers** — Project the cost of a hypothetical workload across providers/models.

Returns models ranked by absolute cost ascending, with
`relative_cost_pct` measured against the cheapest entry
(cheapest = 100%). `models`, if given, restricts the comparison to
those model names. Cost is computed from input/output tokens only;
`RankedEntry.notes` is always `None` in v1 (the field is retained
for future per-row caveats like "tiered pricing approximated").

`include_snapshots=False` (the default) family-dedups the ranked
list: rows sharing both a model-family root (`gpt-5-mini` ↔
`gpt-5-mini-2025-08-07`) AND an identical projected cost collapse
to one representative, with `RankedEntry.variant_count` recording
how many catalog rows the entry stands for. Set
`include_snapshots=True` to see every catalog row (each with
`variant_count=1`) — useful when comparing snapshot-by-snapshot
pricing for production pinning.

- **recommend_provider** — Recommend the cheapest priced model that fits the workload + budget.

v1 ranks by cost only. A future release will incorporate quality
benchmarks (see `quality_snapshot` — the table is reserved for that
purpose) and accept a `quality_priority` axis; for v1 those would
rely on data we don't yet have, so the surface stays cost-only and
honest.

`expected_input_tokens` / `expected_output_tokens` default to a
nominal 1k/1k workload when absent; the `reasoning` notes when
defaults are in use. `budget_usd`, when set, filters out models
that exceed it — if nothing fits, falls back to the cheapest model
overall (the result fields are required, so there's no "no match"
return shape) and the `reasoning` says so plainly.

`providers` / `models` are optional whitelists (AND-combine when
both passed). Both are applied before the budget cut, so an over-
budget fallback returns the cheapest within the filter set rather
than the cheapest priced model overall. A whitelist that matches
nothing raises rather than fabricating a result — likely a
spelling error in the caller's name list.

`task_description` is **optional** and echoed into the reasoning
but does not drive selection — the tool isn't an LLM and can't
interpret free text. Omit it (or pass `None`) and the reasoning
opens with `"Recommending …"` instead of `"For task 'X': …"`.

- **get_pricing** — Return current pricing for one model, one provider, or all models.

Both filters are optional and AND-combined. An unknown
(provider, model) returns an empty list rather than an error — the
caller can distinguish "model not in our table" from "no model
matches your filter" by passing `provider` alone.

- **usage_summary** — Return a one-shot summary of usage over a named calendar period.

`period` is one of today | week | month | year (default: "week").
Boundaries are calendar UTC: `today` = since 00:00 UTC today,
`week` = since Monday 00:00 UTC, `month` = since the 1st of the
month, `year` = since January 1st. Returns totals, the top-3
providers and top-3 models by cost (with `pct` of total), and the
single most expensive call in the window — or `largest_call=None`
when the window is empty.

`include_failed` defaults to `False`: totals, top-N rollups, and
`largest_call` all exclude `success=False` rows (partial-stream
captures and other failure rows). Pass `True` for symmetric
debugging access to the failure population.

- **list_providers** — List every provider we know about, with their models and OpenAI-compat flag.

Sources the provider/model lists from `pricing_snapshot`, so a
provider whose pricing hasn't been seeded simply doesn't appear.
After `bootstrap()` runs on a fresh install this includes every v1
provider (anthropic, openai, qwen, deepseek). Order is alphabetical
by provider, then by model within each provider.


## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "llm-usage-mcp": {
    "command": "uvx",
    "args": ["llm-usage-mcp"]
  }
}
```

## Documentation

## What zhaoyue722/llm-usage-mcp MCP server does

The zhaoyue722/llm-usage-mcp MCP server provides a local ledger for LLM API usage and cost analysis. It supports Anthropic, OpenAI, Qwen, and DeepSeek, including Chinese-provider pricing represented with CNY-to-USD conversion. Data is stored in SQLite at `~/.llm-usage/usage.db`.

The server is a cost meter rather than a request router. It does not select models for live API calls or alter client traffic. Its recommendation tools evaluate recorded or hypothetical workloads using the available pricing catalog.

## How it works

Usage can enter the ledger through the local capture proxy or through the `record_usage` MCP tool. The proxy listens only on `127.0.0.1:5525`, keeps provider keys on the server side, and provides provider-specific routes for Anthropic, OpenAI, DeepSeek, and Qwen-compatible clients. Each recorded call includes token counts, cost, latency, and a request ID. Reusing a request ID makes repeated ingestion idempotent.

Costs are calculated against the pricing table when a usage row is inserted. `query_spend` can group results by provider, model, project, tag, or day, and accepts ISO-8601 time boundaries. Failed rows are excluded by default from spend totals and summaries; callers can include them for capture diagnostics. Calendar summaries cover today, week, month, and year using UTC boundaries.

The comparison and recommendation tools use input and output token counts. `compare_providers` ranks priced models by projected cost, while `recommend_provider` applies optional provider, model, and budget filters. Recommendations are cost-only in the current version; a task description is echoed in the explanation but does not influence model selection.

## Setup and configuration

Install the package with `uv tool install llm-usage-mcp`, or run the MCP entry point with `uvx llm-usage-mcp`. The package requires Python 3.13 or newer according to the project metadata.

For automatic capture, configure the API key for each provider in use: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, or `DASHSCOPE_API_KEY` for Qwen. Start the proxy with `llm-usage-proxy`, then point the client’s matching base URL at the loopback proxy. The proxy can start without every provider key, but requests for an unconfigured provider return a configuration error.

The MCP server communicates over stdio. Claude Code can register it with the `llm-usage-mcp` executable, and the README also identifies Cursor as an MCP client that can use it. A CLI is included for spend, comparison, recommendation, model, provider, status, and proxy operations.

## Tools and capabilities

The MCP surface includes:

- `record_usage` for manually logging a call.
- `query_spend` for filtered, grouped spend windows.
- `usage_summary` for totals, top providers, top models, and the largest call.
- `compare_providers` for projected cross-model pricing.
- `recommend_provider` for cost-based model selection with optional budgets.
- `get_pricing` and `list_providers` for inspecting the local pricing catalog.

The zhaoyue722/llm-usage-mcp MCP server excludes null or empty tags and projects from their respective grouped results. Multi-tag events appear once per tag, so grouped call counts may exceed the total number of calls. Unknown pricing filters return an empty result from `get_pricing`, while provider or model allowlists that match nothing cause recommendation errors.

## Limitations and notes

Pricing and recommendations depend on the seeded local catalog. Recommendation v1 does not use quality benchmarks, and its notes field is reserved for future caveats. If a budget excludes every filtered model, the tool falls back to the cheapest model within the filter set and explains that fallback. The project is local-first and does not provide a hosted SaaS ledger or telemetry service in the supplied material.

_Full upstream README: https://allmcps.com/mcp/zhaoyue722-llm-usage-mcp/readme_