# TokenZero

TokenZero scans code for wasted LLM tokens, compares model pricing, and reshapes request payloads for caching. Use it from a coding agent or CI.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: tokenzero-ai
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/tokenzero-ai/tokenzero
- Updated: 2026-10-28
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/tokenzero

## What it does

TokenZero gives a coding agent tools for inspecting LLM spend patterns. `audit_repo_token_waste` reads the local project and flags large uncached prompts, detached templates, model choices that do not fit simple extraction or classification work, looped LLM calls, and model IDs without current pricing. `calculate_model_arbitrage` compares model options, while `optimize_prompt_payload` sends a supplied request body to the service for adjustment.

The audit is static: it examines source code rather than request traffic, so its cost figures are estimates based on listed prices. The analyzer stays on the machine and can process a diff or fail CI after a chosen recoverable-cost threshold. The MCP package runs through `npx`; the CLI can also initialize a project and add provider base URLs to `.env` after consent.

\`optimize_prompt_payload` sends its input to `https://tokenzero.sh` unless `TOKENZERO_URL` changes the destination. Keep secrets out of that payload. Provider keys pass through the gateway without being stored.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://api.tokenzero.sh/mcp`
- Environment variables: `TOKENZERO_URL`, `TOKENZERO_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http mcp https://api.tokenzero.sh/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env TOKENZERO_URL=<TOKENZERO_URL> --env TOKENZERO_KEY=<TOKENZERO_KEY> --transport stdio tokenzero -- npx -y @tokenzero/mcp
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add tokenzero --url https://api.tokenzero.sh/mcp
```

2. **Platform CLI**
```bash
codex mcp add tokenzero --env TOKENZERO_URL=<TOKENZERO_URL> --env TOKENZERO_KEY=<TOKENZERO_KEY> -- npx -y @tokenzero/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "tokenzero": {
            "url": "https://api.tokenzero.sh/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "tokenzero": {
            "command": "npx",
            "args": [
                "-y",
                "@tokenzero/mcp"
            ],
            "env": {
                "TOKENZERO_URL": "<TOKENZERO_URL>",
                "TOKENZERO_KEY": "<TOKENZERO_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "tokenzero": {
            "type": "http",
            "url": "https://api.tokenzero.sh/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "tokenzero": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@tokenzero/mcp"
            ],
            "env": {
                "TOKENZERO_URL": "<TOKENZERO_URL>",
                "TOKENZERO_KEY": "<TOKENZERO_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http tokenzero https://api.tokenzero.sh/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e TOKENZERO_URL=<TOKENZERO_URL> -e TOKENZERO_KEY=<TOKENZERO_KEY> tokenzero npx -y @tokenzero/mcp
```
Replace <…> with your own values

## When to use it
- spot prompts that lack caching directives
- compare alternative model prices
- check the cost impact of a pull request
- find LLM calls placed inside loops
- prepare a request body for caching

## Example prompts
- Run `audit_repo_token_waste` on this repository and list the token-waste findings.
- Use `calculate_model_arbitrage` to compare models for this request.
- Send this non-secret body to `optimize_prompt_payload` and make it more cache-friendly.

## Similar
- [Gonka — Minority report](https://affpapa.org/en/nevibecode/mcp/gonka-minority-report.md) — MCP server · 431 installs
- [ATOM Pricing Intelligence](https://affpapa.org/en/nevibecode/mcp/atom-pricing-intelligence.md) — MCP server · 4780 installs
- [caveman-learn](https://affpapa.org/en/nevibecode/skills/caveman-learn.md) — skill · 130900 installs
- [hivemind](https://affpapa.org/en/nevibecode/skills/hivemind.md) — skill · 4 installs
- [gsd-surface](https://affpapa.org/en/nevibecode/skills/gsd-surface.md) — skill · 573 installs
- [efficient-dispatch](https://affpapa.org/en/nevibecode/skills/efficient-dispatch.md) — skill · ★ 124 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
