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

Tool	What it does
count_tokens(text, model)	Exact/approximate token count for a piece of text
estimate_cost(text, model, expected_output_tokens)	$ cost estimate for input + optional expected output
compare_models_cost(text, models, expected_output_tokens)	Side-by-side cost table across several models
list_supported_models()	See every model this server has pricing data for

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 Desktop

Local (no Docker):

{
  "mcpServers": {
    "tokenomics": {
      "command": "python",
      "args": ["-m", "tokenomics_mcp.server"],
      "env": { "ANTHROPIC_API_KEY": "your_key_here" }
    }
  }
}

Via Docker:

{
  "mcpServers": {
    "tokenomics": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/absolute/path/to/.env", "tokenomics-mcp"]
    }
  }
}

Restart Claude Desktop, then try: "How many tokens is this prompt for gpt-4o?" or "Compare the cost of this prompt across all supported models."

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.

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.