Skip to main content
Glama
JonThads

Tokenomics MCP

by JonThads
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

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.

Available Tools

4 tools
compare_models_costA

Compare token count and estimated cost for the same text across several models.

Args: text: The input text/prompt models: List of model names to compare. Defaults to a mix of current Anthropic and OpenAI models if not specified. expected_output_tokens: Rough guess at response length, applied to all models

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
modelsNo
expected_output_tokensNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It discloses defaults for 'models' and the meaning of 'expected_output_tokens,' but does not mention whether this is a read-only operation, if it makes external API calls, or any limitations (e.g., pricing database dependence).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, starting with a one-sentence purpose followed by a simple Args list. No wasted words; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has three parameters, an output schema exists, and the description covers all parameter semantics and the core purpose. It leaves little unexplained, though it could benefit from noting when to prefer this over single-model tools like count_tokens or estimate_cost.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear semantic meaning for all three parameters: text is the input, models is a list with a default behavior, and expected_output_tokens is a rough response-length guess applied uniformly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Compare token count and estimated cost for the same text across several models,' which clearly identifies the tool's purpose with a specific verb and resource. This differentiates it from sibling tools like count_tokens (single model) and estimate_cost (single model).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use the tool: when comparing token counts and costs across multiple models. It does not explicitly mention alternatives or exclusions, but the purpose itself strongly signals the use case relative to the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

count_tokensA

Count how many tokens a piece of text would use for a given model.

Args: text: Your text/prompt to tokenize model: Model name, e.g. "claude-sonnet-5", "gpt-5". Call list_supported_models to see all options.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
modelNoclaude-sonnet-5

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool counts tokens, which implies a read-only calculation, but does not explicitly mention whether it sends data externally, rate limits, or any side effects. The behavior is straightforward but minimally disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear one-sentence purpose, followed by a concise Args list. Every element is relevant and there is no redundant or padded text. The structure is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and has an output schema, so the description needn't explain return values. It covers the core purpose and parameter semantics, and even suggests a related tool (list_supported_models). It might benefit from mentioning the default model or clarifying that it's a non-mutating operation, but overall it is sufficiently complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning to 'text' as 'Your text/prompt to tokenize' and clarifies 'model' with examples ('claude-sonnet-5', 'gpt-5') and a pointer to list_supported_models. This provides practical guidance beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource: 'Count how many tokens a piece of text would use for a given model.' This clearly distinguishes the tool from sibling tools like estimate_cost (which estimates cost) and list_supported_models (which lists model options).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through its purpose but provides no explicit when-to-use or when-not-to-use guidance compared to sibling tools. The only hint is 'Call list_supported_models to see all options,' which addresses model selection rather than tool selection. There are no exclusions or alternative tool references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

estimate_costA

Estimate the API cost of sending this text as input, plus optional expected output.

Args: text: The input text/prompt model: Model name, e.g. "claude-sonnet-5", "gpt-5" expected_output_tokens: Rough guess at response length (default 0 = input only)

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
modelNoclaude-sonnet-5
expected_output_tokensNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for disclosing behavior. It does not state whether the tool is read-only, makes external network calls, or uses live pricing data. While 'estimate' implies no actual API invocation, this is not explicit, leaving significant transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficient: a single-sentence purpose followed by a concise Args list. It is front-loaded and not overly verbose. The minor redundancy with schema defaults (e.g., default values repeated) prevents a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity and the presence of an output schema, the description is adequate for basic usage. However, it lacks guidance on when to choose this tool over siblings like compare_models_cost, and offers no behavioral notes (e.g., whether it requires network access). These are notable gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero descriptive coverage, but the description compensates fully. It explains the 'text' parameter as 'input text/prompt', gives concrete model name examples, and clarifies 'expected_output_tokens' as a rough guess at response length with a default of 0 meaning input only. This adds meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Estimate the API cost of sending this text as input, plus optional expected output.' It uses a specific verb ('estimate') and resource (API cost), and distinguishes itself from sibling tools like count_tokens and compare_models_cost by focusing on cost estimation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when an API cost estimate is needed for an input text and optional output length. However, it does not explicitly mention alternatives or exclusions relative to sibling tools, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_supported_modelsA

List all models this server has pricing data for, with their current rates.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It adds value by specifying that only models with pricing data are included and that current rates are shown, clarifying the tool's read-only nature without needing explicit safety hints. It does not address potential quirks like pagination, but for a simple list operation this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence. Every word contributes to stating the tool's purpose and the content of the list, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and an output schema exists, the description is sufficient for an agent to select and invoke the tool correctly. It clearly conveys what the tool does and what data is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description provides no parameter details, but none are needed; the mention of 'current rates' hints at the output structure without describing parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list), resource (models), and scope (models with pricing data and their rates). This distinguishes it from sibling tools like count_tokens or estimate_cost, which handle calculations rather than enumeration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the foundational tool for discovering available models, but it does not explicitly mention when to use it instead of siblings or provide exclusions. Usage guidance is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedcompare_models_cost
    • First observedcount_tokens
    • First observedestimate_cost
    • First observedlist_supported_models
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: counting tokens, estimating cost, comparing costs across models, and listing supported models. There is no overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: count_tokens, estimate_cost, compare_models_cost, list_supported_models. The naming convention is uniform and predictable.

Tool Count5/5

Four tools is well-scoped for this server's purpose. Each tool addresses a core aspect of tokenomics (counting, costing, comparing, and model discovery) without unnecessary redundancy.

Completeness5/5

The tool set covers the full lifecycle of token cost analysis: list available models, count tokens, estimate cost, and compare across models. There are no obvious missing operations for the declared purpose.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • llm-token-tracker

    wn01011
    A
    license
    B
    quality
    D
    maintenance
    Token usage tracker for OpenAI and Claude APIs with MCP (Model Context Protocol) support.
    6
    182 npm
    5
    MIT

  • UsageWall

    agenciabakucl-coder
    A
    license
    Not graded
    quality
    D
    maintenance
    Live LLM pricing as an MCP server. Ask Claude or any MCP client 'how much does this prompt cost?' and get real numbers from a hand-checked pricing table for every major LLM.
    MIT

  • ai-cost-calculator-api

    lazymac2x
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI cost calculation, comparison, and optimization across major providers like Anthropic, OpenAI, Google, Meta, and Mistral. Supports cost estimation, budget-aware model finding, and token estimation through a simple API and MCP integration.
    -