Metadata-Version: 2.5
Name: llmledger-mcp
Version: 0.1.8
Summary: Which AI model, and what it costs: LiteLLM prices, Arena ratings and price history, inside Claude and other AI apps.
Project-URL: Homepage, https://pouriaetab.github.io/llmledger/
Project-URL: Source, https://github.com/pouriaetab/llmledger/tree/main/mcp
Project-URL: Issues, https://github.com/pouriaetab/llmledger/issues
License-Expression: MIT
License-File: LICENSE
Keywords: fastmcp,litellm,llm,mcp,model selection,pricing
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: fastmcp==4.1.0
Description-Content-Type: text/markdown

# llmledger-mcp

<!-- mcp-name: io.github.pouriaetab/llmledger -->

Ask Claude (or Cursor, ChatGPT desktop, any app that speaks MCP) which AI model to use and what it
costs, in the middle of your work. The answers come from [llmledger](https://pouriaetab.github.io/llmledger/):
LiteLLM's public price catalogue, Arena's ratings by task, and every price change since 2023 with how
likely a price is to change next. Rebuilt every day.

## Install

Needs [uv](https://docs.astral.sh/uv/). Nothing to host and no keys: the plug-in runs on your computer
and reads the day's data from the llmledger page, cached for a day, with a bundled copy for offline use.

Claude Code:

```bash
claude mcp add llmledger -- uvx llmledger-mcp
```

Claude Desktop (Settings, Developer, Edit config) or Cursor (`.cursor/mcp.json`):

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

A LiteLLM proxy can offer it to a whole team through its MCP gateway, as a stdio server with the same
command.

The same answers also come as an Agent Skill, which takes far less of an agent's context until it is used
and needs only Python: the folder `skills/llmledger` in the repository,
https://github.com/pouriaetab/llmledger/tree/main/skills/llmledger
In Claude Code: `/plugin marketplace add pouriaetab/llmledger`, then `/plugin install llmledger@llmledger`.

## What you can ask

| Tool | For example |
|---|---|
| `suggest_for_project` | "Which model and effort for this project?" with the starting prompt; `pay` can be `claude` or `chatgpt` to compare within a plan |
| `compare_models` | "Opus 5.5 or Fable 5.1 for coding, and when is Fable cheaper?" |
| `estimate_cost` | "What do 2,000 calls a day of 10K tokens in and 1K out cost on these three?", and with `cached_tokens` and `cache_write_tokens`, how much the cache saves |
| `find_models` | "The best rated coding models under $10 per 1M answer tokens that read images" |
| `price_history` | "Has Claude Opus 5.5's price changed, and how likely is it to change soon?"; with `date`, "What did it cost on 1 March?" Each change links the LiteLLM change behind it |
| `not_yet_priced` | "Which new models on Arena have no price yet, and how long does a price usually take?" |
| `estimate_time` | "How long will 5,000 calls of 2K tokens in and 600 out take on Opus 5.5 through the API, 4 at a time?" Learned from your own runs |
| `log_run` | "I timed this call: 2,100 in, 640 out, 9.2 seconds", or a promptfoo results file; kept on your computer only |
| `forecast_job` | "Here is a promptfoo run of 20 of my 5,000 tests: what will the whole job cost and take on each model, and which should I pick?" Reads the file only |
| `local_or_cloud` | "Should I buy a $2,000 computer to run llama3.1:8b at home, or keep paying for GPT-6.1 at 30,000 calls a month?" The local model's speed from your own runs, electricity from EIA or your price |

Plus a resource, `llmledger://snapshot` (data dates and sources), and a prompt, `pick_a_model`.

## Good to know

- Costs and ratings are estimates. Arena ratings say which answers people preferred, not what will work
  best for you. Plan use (Claude, ChatGPT) assumes a plan runs down in step with API prices, because
  plans do not publish per-model limits. Not financial or procurement advice.
- Effort levels come from LiteLLM; the suggested level is a rule of thumb. No open source measures
  tokens per task at each effort level yet.
- Many price changes in the catalogue fix a wrong entry rather than change a price: in a labelled sample,
  about 6 in 10 first price changes. `price_history` says what each flag on a change means (a likely
  correction, a unit fix, a change undone) and how often such changes were corrections.
- Every answer carries the date of its data. When the data is 3 or more days old, the answer says so.
- Times come only from your own runs (and the sample's own timed calls for `forecast_job`), always as a
  usual time and a slow day. How often a model was right is the share of a sample's checks it passed, with
  a 95% range; with 20 tests the range is wide, and the answer says when two models cannot be told apart.
- What the plug-in reads: a prompt given to `suggest_for_project` is only counted and matched against word
  lists; a promptfoo results file (`log_run`, `forecast_job`) is read for numbers and names only (provider id,
  latency, token counts, pass or fail), and the prompts, answers and grader text inside it are never passed on
  or treated as instructions. Timed runs stay on your computer as numbers. The only network call is the daily
  download of `data.json`.
- Set `LLMLEDGER_DATA` to a local data.json or another address to use your own copy.

## Data and licences

Prices: LiteLLM's `model_prices_and_context_window.json` (MIT). Ratings: the Arena leaderboard
(CC BY 4.0). Electricity: the U.S. Energy Information Administration's Electric Power Monthly
(public domain). Price history and outlook: [llmledger](https://github.com/pouriaetab/llmledger) (MIT).
Built with [FastMCP](https://github.com/PrefectHQ/fastmcp) (Apache-2.0). Independent; not affiliated
with BerriAI, LiteLLM or Arena.
