Tokenomics MCP

An MCP server for counting LLM prompt tokens and estimating API costs across OpenAI and Anthropic models — right inside your chat client, no browser-based token counter needed.

Tools

Related MCP server: nikhilnt

How token counting works

• OpenAI models (gpt-4o, gpt-4.1, gpt-5, o3, etc.): exact, via tiktoken.

• Claude models: exact via Anthropic's count_tokens API if ANTHROPIC_API_KEY is set; otherwise falls back to a tiktoken-based approximation, and says so explicitly in the output.

Pricing data lives in src/tokenomics_mcp/pricing.py as a plain dict — PRICING_LAST_VERIFIED marks the date it was checked. LLM pricing changes often; update that dict directly when it does.

Project layout

tokenomics-mcp/
├── src/tokenomics_mcp/
│   ├── server.py       # MCP tool wiring (thin layer)
│   ├── pricing.py       # pricing table + token-counting logic (unit-tested)
│   └── __init__.py
├── tests/
│   └── test_pricing.py  # pure-logic tests, no network/API calls needed
├── Dockerfile            # multi-stage build, non-root runtime user
├── docker-compose.yml
├── .github/workflows/
│   ├── ci.yml            # lint + test on every PR/push to main
│   └── docker-publish.yml # build + push image to GHCR on version tags
├── pyproject.toml
└── .env.example

Local development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env    # optional: add ANTHROPIC_API_KEY for exact Claude counts

ruff check .             # lint
pytest -v                # test
python -m tokenomics_mcp.server   # run the server standalone (stdio)

Running with Docker

docker build -t tokenomics-mcp .
docker run -i --rm --env-file .env tokenomics-mcp

MCP servers communicate over stdio, not a network port — that's why the Dockerfile has no EXPOSE and the run command uses -i (keep stdin open) rather than -p (publish a port). docker-compose.yml wraps the same invocation if you prefer docker compose run tokenomics-mcp.

Connect it to Claude Code

This server is only verified working as an MCP server for the Claude Code CLI, registered with the claude mcp command — not by hand-editing a config file.

pip install -e .   # or: pip install -e ".[dev]"
claude mcp add tokenomics -s user -- "/absolute/path/to/tokenomics-mcp"
# Windows: claude mcp add tokenomics -s user -- "C:\path\to\repo\.venv\Scripts\tokenomics-mcp.exe"

Use -s user (global scope), not the default local/project scope. Local-scope entries are stored keyed by the literal, unnormalized path string of the project directory in ~/.claude.json. Different entry points into Claude Code (a plain shell vs. an IDE extension) can normalize the same directory to different strings — C:/Projects/tokenomics vs. C:\Projects\tokenomics vs. c:/Projects/tokenomics all key separately on Windows — so a server added under one key silently doesn't exist under another, with no error. User scope isn't keyed by path at all, so it avoids this entirely and works from any project.

After adding it, restart your Claude Code session (/mcp only reflects the server list a session loaded at startup) and confirm with /mcp — you should see tokenomics listed as connected with 4 tools. Then try: "How many tokens is this prompt for gpt-4o?" or "Compare the cost of this prompt across gpt-4o, gpt-5, and claude-sonnet-5."

Claude Desktop is not supported

Claude Desktop reads its own separate config file (claude_desktop_config.json), unrelated to Claude Code's ~/.claude.json. Registering the server there has not been made to work reliably — edits to that file were observed to silently revert — so treat Claude Desktop as unsupported for this server until that's investigated further.

CI/CD

• ci.yml runs on every PR and push to main: installs the package, lints with ruff, runs the pytest suite. All logic in pricing.py is unit-tested with stubbed tokenizers, so tests run fast with no network calls or API keys required.

• docker-publish.yml runs when you push a version tag (git tag v0.1.0 && git push origin v0.1.0): builds the Docker image and pushes it to GitHub Container Registry (ghcr.io/<your-username>/tokenomics-mcp), tagged both with the version and latest. No registry account setup needed — it authenticates with the GITHUB_TOKEN GitHub Actions already provides.

Releasing a new version

1. Bump version in pyproject.toml and __version__ in __init__.py.

2. Commit, merge to main.

3. Tag and push: git tag v0.2.0 && git push origin v0.2.0.

4. Watch the Publish Docker image workflow run in the Actions tab — once green, the image is live at ghcr.io/<your-username>/tokenomics-mcp:v0.2.0.

Limitations

• Claude Code CLI only. See "Connect it to Claude Code" above — Claude Desktop is not currently supported.

• Must be registered at user scope (claude mcp add -s user), not local scope, due to the path-key normalization issue described above. Project scope (a checked-in .mcp.json) has not been tested with this server.

• New sessions required after registering or changing the server. A running Claude Code session doesn't pick up MCP config changes made outside it — start a fresh session and check /mcp to confirm the tools are live.

• Claude token counts are exact only with ANTHROPIC_API_KEY set. Without it (or if the API call fails for any reason), count_tokens and estimate_cost fall back to a cl100k_base tiktoken approximation for Claude models. The response's Method: line always says which path was used — check it if you need guaranteed-exact counts.

• Pricing is a static, hand-maintained table, not a live feed. Rates can drift from what a provider actually charges; PRICING_LAST_VERIFIED in pricing.py shows how stale it might be, and the tool output repeats that date so you know to double check for anything cost-sensitive.

• No network calls beyond the optional Claude token-count API. Anything it can't compute locally (OpenAI counts, Claude counts without an API key) is an approximation by design, not a bug.

Notes

• The pricing table needs periodic manual updates; there's no live pricing feed to scrape reliably, so this is intentionally a plain, editable dict rather than something auto-fetched.