Skip to main content

tokenwise 🪙

You're already paying for tokens. At least stop wasting them.

tokenwise is a free, local MCP server that gives your AI-powered IDE full visibility into context window usage — before you hit the wall and your AI gets dumb.

Works with Cursor, Claude Code, Windsurf, Cline, Continue, and any MCP-compatible client.


The Problem

You're coding with AI. Things are going great. Then suddenly — the responses get vague, it forgets what you told it 10 messages ago, and you have no idea why.

You just silently hit your context window limit.

You had no warning. No visibility. No control.

tokenwise fixes that.


What It Does

tokenwise runs as a local MCP server on your machine. No data leaves your computer. No API key needed. No cost.

It exposes tools your IDE can call to understand exactly what's happening with your context:

Tool What it does
count_tokens Count tokens for any text, for any model
analyze_context Break down token usage by system prompt, history, and files
get_model_limits Get the context window size for any supported model
warn_threshold Get alerted at 70%, 85%, and 95% usage

Example output from analyze_context

Context Usage [claude-sonnet-4-5]
████████████░░░░░░░░ 62% (124,000 / 200,000 tokens)
├── System Prompt:  8,200
├── IDE Hidden Rules: 4,100
├── Conversation:   68,300
├── Files:          43,400
└── Available:      76,000

Note: tokenwise also automatically checks your folder for things like .cursorrules or .clinerules so their hidden token usage is correctly included in the total. It just counts the tokens locally—nothing is ever stored or sent out.

Example output from warn_threshold

⚠️  95% threshold crossed — 192,400 / 200,000 tokens used (96.2%). Consider trimming context.

  Model:      claude-sonnet-4-5
  Tokens:     192,400 / 200,000
  Usage:      96.2%
  Triggered:  70%, 85%, 95%

Example output from get_model_limits

If you ever forget what the maximum limit is for the specific model you're chatting with, just ask your AI "what is the limit for gemini-2.0-pro?" and it will check its internal registry:

Model:    gemini-2.0-pro
Provider: Google
Limit:    1,000,000 tokens (1000k)

Supported Models

Provider Models
Anthropic Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku, Claude 4 series
OpenAI GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo, o1, o3
Google Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0
Meta Llama 3, Llama 3.1, Llama 3.2
Mistral Mistral 7B, Mixtral 8x7B, Mistral Large
Fallback Any unknown model (character-based estimation)

Installation

Requirements

  • Python 3.10+
  • Any MCP-compatible IDE (Cursor, Claude Code, Windsurf, etc.)

Install from PyPI

pip install mcp-tokenwise

Configure in your IDE

Cursor / Windsurf — add to your MCP config (~/.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "tokenwise": {
      "command": "python",
      "args": ["-m", "tokenwise"]
    }
  }
}

Claude Code:

claude mcp add tokenwise python -m tokenwise

That's it. Restart your IDE and tokenwise is live.


Usage Examples

Once connected, you can ask your AI assistant directly:

"How many tokens am I using right now?"
"Am I close to my context limit?"
"Break down what's eating my context window"
"What's the token limit for GPT-4o?"

tokenwise handles it automatically in the background.


Roadmap

Phase 1 — Visibility (current)

  • Token counting for all major models
  • Context breakdown by component
  • Model limit registry
  • Threshold warnings (70 / 85 / 95%)

Phase 2 — Active Management (coming soon)

  • trim_context — intelligently remove least relevant parts
  • compress_history — summarize old turns to free space
  • prioritize_files — rank files by relevance to current task
  • suggest_split — detect when a task should be broken up

Why Local-Only?

Your code is private. Your conversations are private. tokenwise never phones home — it runs entirely on your machine, reads nothing, stores nothing.

If you're already paying $20–200/month on AI tools, the last thing you need is another service with access to your codebase.


Contributing

tokenwise is early and we'd love contributions:

  • Add tokenizer support for a new model family
  • Improve estimation accuracy for edge cases
  • Test with a new MCP client and report back
  • Suggest a Phase 2 feature

Open an issue or PR — all welcome.


License

MIT — free forever.


Built because every developer deserves to know where their tokens are going.

Metadata

Release files for mcp-tokenwise 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-tokenwise 0.1.0
File Size Uploaded Provenance Actions
mcp_tokenwise-0.1.0.tar.gz 9.8 kB Without provenance Details for mcp_tokenwise-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-tokenwise 0.1.0
File Interpreter ABI Platform Actions
mcp_tokenwise-0.1.0-py3-none-any.whl Python 3 none any Details for mcp_tokenwise-0.1.0-py3-none-any.whl

Total release size: 20.6 kB

Release files / mcp_tokenwise-0.1.0.tar.gz

Download URL mcp_tokenwise-0.1.0.tar.gz
Size 9.8 kB
Tags Source
SHA-256 checksum
How to use checksums
76b23da0c9dc59ce0ad4b6d6598e25d685097b487b935941bb0f02cff531608f
BLAKE2b-256 checksum
How to use checksums
f37556dd1a976063e1d945c7f2fdd7995396548dde0e712976a4509d675baab4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.13

Release files / mcp_tokenwise-0.1.0-py3-none-any.whl

Download URL mcp_tokenwise-0.1.0-py3-none-any.whl
Size 10.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2fa63e99352b0a8e3a6cd3654be661b9a4649834fc0640a7cf69acbd120bdde9
BLAKE2b-256 checksum
How to use checksums
dccbfa63afc70c209aa2b8d2985bc26ef5cceef868604c1cffaf29185082a936
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.13

Security for mcp-tokenwise 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page