Why TokenSaver?

Every API call sends more tokens than necessary. Conversation history accumulates. Web pages arrive as raw HTML. Tool results get re-fetched on every turn. System prompts bloat over iterations.

TokenSaver intercepts each of these patterns and fixes them at the agent level — no model changes, no prompt engineering, no plan upgrades.

Tools

All tools work fully offline — no API key required for core features.

Installation

git clone https://github.com/pozii/tokensaver.git
cd tokensaver
pip install -e .

Python 3.11+ required. On first use, compress_context will auto-download the NLTK punkt_tab tokenizer (~2 MB) if not already present.

How it connects to your AI client

TokenSaver has no URL and runs no background server by default. It uses stdio transport: the AI client reads your config, spawns python -m tokensaver as a child process, and talks to it through stdin/stdout. You never open a port or start anything manually — the client does it for you when it launches.

Your AI client  ──spawn──▶  python -m tokensaver  ──stdio──▶  tools available

The alternative is SSE transport, where you start the server yourself on a local port and the client connects over HTTP. This is useful for multi-agent setups or when multiple clients share the same server instance.

Setup

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Save the file and restart Claude Desktop. The tokensaver tools will appear in the tool list.

Claude Code

claude mcp add tokensaver -- python -m tokensaver

Or add manually to ~/.claude/settings.json:

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

OpenCode

Config file: ~/.config/opencode/config.json

{
  "mcp": {
    "servers": {
      "tokensaver": {
        "type": "local",
        "command": ["python", "-m", "tokensaver"]
      }
    }
  }
}

Any MCP-compatible client (SSE mode)

Start the server once:

python -m tokensaver --transport sse --port 8765

Then point your client at:

http://localhost:8765/sse

Fixing Python path issues

If your system has multiple Python versions and python resolves to the wrong one, use the full path:

# Find the right Python
which python3        # macOS / Linux
where python         # Windows

Then use the full path in your config:

{
  "mcpServers": {
    "tokensaver": {
      "command": "/usr/local/bin/python3",
      "args": ["-m", "tokensaver"]
    }
  }
}

{
  "mcpServers": {
    "tokensaver": {
      "command": "C:\\Python314\\python.exe",
      "args": ["-m", "tokensaver"]
    }
  }
}

Usage

Recommended workflow

Each turn:
  1. count_tokens          → How large is my current context?
  2. advise_context_window → Am I approaching the model's limit?

Before expensive tool calls:
  3. cache_get             → Did I already run this?

When fetching web content:
  4. extract_webpage       → Clean text, not raw HTML

When history grows long:
  5. prune_conversation    → Drop filler turns, compress old ones
  6. compress_context      → Shrink large injected context blocks

When writing system prompts:
  7. optimize_prompt       → Remove redundant phrasing

Tool reference

{
  "content": "Some long text or list of messages...",
  "model": "claude-sonnet-4",
  "include_message_overhead": true
}

{
  "text": "3,000-token context block...",
  "target_tokens": 600,
  "mode": "extractive"
}

# Standard pattern: check before running
key = cache_key("extract_webpage", {"url": "https://example.com"})
hit = cache_get(key=key)

if not hit["hit"]:
    result = extract_webpage(url="https://example.com")
    cache_store(key=key, value=str(result), ttl_seconds=3600)

{
  "url": "https://example.com/article",
  "max_tokens": 2000,
  "include_links": false,
  "include_metadata": true
}

{
  "path": "/home/user/myproject",
  "mode": "both",
  "max_tokens": 500,
  "file_extensions": [".py", ".md"],
  "max_depth": 3
}

{
  "messages": [...],
  "max_output_tokens": 2000,
  "keep_last_n": 4,
  "prune_strategy": "hybrid"
}

{
  "prompt": "Please make sure to always answer questions...",
  "optimization_level": "medium",
  "preserve_constraints": true,
  "output_format": "prose"
}

{
  "model": "gpt-4o",
  "current_tokens": 110000,
  "messages": [...],
  "target_utilization": 0.75
}

Optional: LLM-backed summarization

For higher-quality abstractive compression on very large texts (>5,000 tokens):

pip install "tokensaver-mcp[llm]"

Set ANTHROPIC_API_KEY in your environment or a .env file, then use mode: "abstractive" in compress_context.

Running Tests

pip install -e ".[dev]"
python -m pytest tests/ -v

38 tests — all offline, no API key or network required.

Project Structure

src/tokensaver/
  server.py          # FastMCP app, tool registration
  models.py          # Context window table, shared types
  tools/
    counter.py       # count_tokens
    compress.py      # compress_context
    cache.py         # cache_store / cache_get / cache_invalidate
    extractor.py     # extract_webpage
    summarizer.py    # summarize_file
    pruner.py        # prune_conversation
    optimizer.py     # optimize_prompt
    advisor.py       # advise_context_window
  utils/
    token_utils.py   # tiktoken wrapper
    text_utils.py    # sentence splitting, deduplication