Llm Usage & Cost Tracker

by zhaoyue722

883 downloads

Not rated

GitHub

Description

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…

About

Details

Author: zhaoyue722
Downloads: 883
Categories: Developer Tools, AI, Other

- Local-first SQLite storage, no telemetry.
- Supports Anthropic, OpenAI, DeepSeek, and Qwen.
- MCP server with seven query tools.
- CLI with subcommands for spend, compare, recommend.
- Capture proxy logs all API calls idempotently.
- Cross-provider cost comparison and recommendation.
- Works with streaming and non-streaming calls.
- No SaaS signup or account needed.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Llm Usage & Cost Tracker

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

From the repository

Install via uv tool install llm-usage-mcp (or clone from source). Set at least one provider API key as an environment variable. Run the capture proxy (llm-usage-proxy), which listens on 127.0.0.1:5525. Point your LLM client’s base URL to the proxy. Use the MCP server (e.g., claude mcp add llm-usage -- uv run llm-usage-mcp) to ask agent questions, or run CLI commands like llm-usage spend, llm-usage compare, and llm-usage recommend.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "llm usage & cost tracker": {
            "llm-usage": {
                "command": "uvx",
                "args": [
                    "llm-usage-mcp"
                ]
            }
        }
    }
}

McpServers

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

LLM Usage & Cost Tracker — your local-first spend watchdog

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 costmeter, 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:

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-mcpcaptures every call you make into one local store, costs it correctly per provider at the moment it happens, and hands the answer backtwo 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.

- 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, …) areon the way.

Two minutes fromgit cloneto your first captured call. This part is aboutcapture— getting calls recorded.Reading the data backcomes next.

Install from PyPI with uv(orpipx) — this puts the three console scripts on yourPATH:

uv tool install llm-usage-mcp # or: pipx install llm-usage-mcp

Prefer to hack on it? Clone and sync from source instead:

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 tollm-usage proxy.

The Quickstart below usesuv run …(the from-source workflow). If you installed from PyPI, the scripts are already on yourPATH— drop theuv runprefix, and register the MCP server withclaude mcp add llm-usage -- llm-usage-mcp.

You only need a key for the provider(s) you actually use; the proxy starts regardless and per-route requests return503 configuration_errorfor any provider whose key is missing.

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.exampleto.envand fill in).

It bindsloopback-only(127.0.0.1:5525) — never reachable from the network. The proxy holds your API keys server-side; clients never need them.

The proxy exposes one route per provider. Set the matching_BASE_URLenv var on the client side:

Example — launch Claude Code with calls routed through the proxy:

ANTHROPIC_BASE_URL=http://127.0.0.1:5525 claude

Make a call through your agent (or any client pointed at the proxy), then check it landed:

Every call lands in~/.llm-usage/usage.dbwith tokens, cost, latency, and arequest_idfor idempotency — and shows up in that headline. That's the whole loop: capture on one side, answers on the other.

Once calls are being captured, you read them back two ways. Same data, same numbers — pick whichever fits the moment.

Register the MCP server with Claude Code:

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.

query_spendandusage_summarydefault toinclude_failed=falseso partial-stream rows don't pollute totals; opt-in via the param.

The same questions, as a CLI — eight subcommands under onellm-usageconsole, for when typing is faster than asking your agent.

The examples below assumellm-usageis on yourPATH— eithersource .venv/bin/activateoruv tool install .. Otherwise, prefix each command withuv run(e.g.uv run llm-usage spend).

$ 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.

Conventions that hold across every command:

- --jsonemits the same Pydantic shape the matching MCP tool returns. Pipe straight intojq.
- --color {auto,always,never}honorsNO_COLORand 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/-Vprints the version and exits.--install-completion {bash|zsh|fish|powershell}installs a tab-completion script — one shell restart later, every flag is<Tab>-able.

Rank every priced model by projected cost for ann-input /m-output call. Cheapest first, percent against the cheapest. Default view family-deduplicates rows that share both a model family rootand*an identical price — sogpt-5-miniandgpt-5-mini-2025-08-07collapse to one row with×2. Pass--allto see every catalog row.

# 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]'

Catalog browser. Sibling ofcompare, 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 inputor--sort outputto 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.

# 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

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.

# 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.--taskis optional and surfaces in the reasoning text; it doesn't drive selection (the tool isn't an LLM and can't interpret free text).

Read the SQLite. The default view is ausage_summaryheadline — total dollars, top-3 providers, top-3 models, largest single call. Pass--group-byto switch into rollup mode.

# 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.

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 printsdatabase not initializedrather than silently creating the file.

$ 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

Per-provider configuration view. Wider than thestatusProviders block: adds the wire-format flag (openai-compat: yes/no) and an optional--modelsexpansion that lists every priced model under each provider.

$ llm-usage providers $ llm-usage providers --models # expand each provider with its model list

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.

$ llm-usage about # Machine-readable, for a script or an issue template: $ llm-usage about --json

More on the way.Google Gemini, AWS Bedrock, Moonshot (Kimi), Zhipu GLM, MiniMax, and others are scoped indocs/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.

Everything is env vars (or a.envfile 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:

A minimal Dockerfileis includedonlyfor 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 stilluvx llm-usage-mcplocally — this is a local-first tool, not a hosted service.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Local-first knowledge graph for developers. Watches project files, extracts entities and relationships via LLMs, and lets you query across projects with natural language and source citations.

Open-source tool for collaborative editing, versioning, evaluating, and releasing prompts.

next-devtools-mcp is a MCP server that provides Next.js development tools and utilities for AI coding assistants like Claude and Cursor.

Word search, crossword, and sudoku generator MCP server with printable PDF worksheets, themed word banks, and verifiable LLM evals. Local-first, from the makers of puzzletide.com.

A demonstration server for ActionKit, providing access to Slack actions via Claude Desktop.

MCP server that lets Claude Code agents delegate tasks to agents in other project directories, with parallel dispatch, sessions, and async jobs.

Statistical regression testing for LLM agents: p-value, effect size, and CI on behavior change.

A Python MCP package that gives your LLM agents complete file system and shell capabilities — production-ready, sandboxed, and wired to any LLM in minutes.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Description

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Install

More like this

Sequential Thinking

Sentry

Github

Filesystem

EverArt

Google Drive