token-saver-mcp

An MCP server plugin for Claude Code that automatically reduces token usage across your sessions. All optimizations are purely algorithmic — no extra API calls, no added cost.

Tools

Tool	What it does
compress_text	Strips comments (//, /* */, #, <!-- -->), blank lines & whitespace from code/prose. String-aware: never corrupts URLs, #hashtag/#fff hex colors, or markers inside string literals; comments inside template-literal ${} expressions are stripped
smart_read_file	Reads only relevant sections of a file. Structure-aware across JS/TS, Python, Go, Rust, Java & C#: returns the complete enclosing function/class/interface around keyword matches, with a configurable fallback window. Rejects binary files
summarize_output	Truncates long command output / logs to a token budget. Preserves error/failure lines anywhere in the output, keeps head + tail, collapses duplicate lines
summarize_diff	Compacts a unified git diff: keeps file headers, hunk headers & changed lines; strips context lines and index/mode noise. Renames and binary files are annotated
count_tokens	Counts token usage for any text (cl100k_base encoding)
generate_claudeignore	Generates a .claudeignore covering Node, Python, Rust, Go, Java, Ruby, PHP & Terraform artifacts plus modern tooling caches (Turbo, Vercel, Nuxt, SvelteKit, Storybook), seeded from your existing .gitignore
optimize_prompt	Rewrites verbose prompts to be concise (~40 filler-phrase rules). Fenced code blocks and inline code are passed through untouched

All tools return plain text with a compact stats footer — results are deliberately not JSON-wrapped, since JSON escaping of newlines and quotes would inflate the very token count this server exists to reduce.

Note on token counts: the server uses the cl100k_base encoding (via tiktoken), which is OpenAI's tokenizer. Claude's tokenizer differs, so all counts are approximations — typically within ~10–20% of Claude's actual usage. Relative savings percentages are unaffected.

Benchmark results

Measured against real code fixtures and realistic prompt inputs. See benchmark/BENCHMARK.md for full methodology.

Tool	Avg token reduction	Best case
compress_text	31%	53% on JS with JSDoc
smart_read_file	44%*	81% extracting one function from a module
summarize_output	76%	84% on long build output
summarize_diff	50%	53% on a multi-file diff with renames
optimize_prompt	28%	52% on heavily padded prompts
count_tokens	accuracy tool — no reduction metric	—
generate_claudeignore	structural correctness tool — no reduction metric	—

* the smart_read_file average includes tiny synthetic fixtures used as multi-language correctness tests; on realistic files it ranges 38–81%.

Run the benchmark yourself:

npm run benchmark

---

Installation

1. Clone and install

git clone <your-repo-url> token-saver-mcp
cd token-saver-mcp
npm install

2. Add to Claude Code

claude mcp add token-saver -- node /absolute/path/to/token-saver-mcp/src/index.js

Or manually edit ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "token-saver": {
      "command": "node",
      "args": ["/absolute/path/to/token-saver-mcp/src/index.js"]
    }
  }
}

3. Verify

claude mcp list

You should see token-saver listed as connected.

---

Usage examples

Use smart_read_file on src/api/routes.js, focus on "authentication" and "middleware"

Generate a .claudeignore for my project at /home/user/myapp and write it to disk

Count tokens in this output: [paste output]

Compress this before sending: [paste code]