token-filter-mcp
An MCP server that wraps developer tools (shell, file reads, grep, tests, git) and compresses their output to save context window tokens while preserving errors and actionable info.
filtered_shell: Run any shell command with smart/aggressive/passthrough filtering, auto-detecting command type (tests, git, linters, installs) to strip noise and keep errors.
filtered_read: Read files in three modes: full (compact whitespace/license/imports), signatures (declarations only), relevant (focus pattern with ยฑ10 lines context).
filtered_grep: Search regex patterns in directories, results grouped by file/match, deduplicated with [รN] counts, uses ripgrep when available.
smart_test: Execute test commands (Jest/Vitest/pytest/cargo/go) and return only failures with locations, expected vs received, truncated stacks; optional show_passes and coverage.
smart_git: Compact git status/diff/log and action results (commit, push, pull, add, branch) with one-line summaries and filtered hunks.
Smart ADB (in README, not in schema): Android automation via dump/tap/key/type/swipe/long_press/install/logcat operations using locators instead of screenshots.
metrics_summary (README only): Query saved metrics (invocation counts, chars saved, per-tool breakdown) without reading JSONL files.
Configuration: Optional per-project or global JSON config to adjust filtering defaults and per-command overrides.
Filters output from Biome linter, grouping errors by rule and omitting clean files.
Filters output from ESLint linter, grouping errors by rule and omitting clean files.
Provides smart filtering for git operations such as status, diff, log, commit, push, and pull, returning concise summaries.
Supports reading JavaScript files with modes like 'signatures' (only declarations) and 'relevant' (sections matching focus pattern with context).
Filters output from Jest test runner, removing passing tests and displaying only failure details with file location and expected/received values.
Filters output from npm commands, returning a compact summary of packages installed instead of full resolution trees.
Filters output from pytest test runner, showing only test failures with location and expected/received values.
Supports reading Python files with modes like 'signatures' (only declarations) and 'relevant' (sections matching focus pattern with context).
Filters output from Ruff linter, grouping errors by rule and omitting clean files.
Supports reading Rust files with modes like 'signatures' and 'relevant', and filters output from cargo test, showing only test failures.
Supports reading TypeScript files with modes like 'signatures' (only declarations) and 'relevant' (sections matching focus pattern with context).
Filters output from Vitest test runner, showing only test failures with location and expected/received values.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@token-filter-mcp run npm test and show only failures"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐งน token-filter-mcp
Your LLM is wasting 80% of its context window on noise. This fixes that.
An MCP server that sits between your AI coding assistant and its tools, intelligently compressing outputs before they consume your precious context. Longer sessions. Better reasoning. Lower costs.
๐ธ The Problem Nobody Talks About
Every time your AI assistant runs a command, it dumps the entire raw output into its context window:
+ โ src/auth.test.ts (14 tests) โ you don't need this
+ โ src/utils.test.ts (8 tests) โ or this
+ โ src/payments.test.ts (12 tests) โ or this
+ โ src/users.test.ts (10 tests) โ or this
- โ src/orders.test.ts (3 tests) โ THIS is what matters
- โ should validate quantity > 0
- Expected: error
- Received: successThe vast majority of tool output is noise: tests that pass, git headers, resolution trees, progress bars, whitespace. ~80% of what goes into the context window is information the LLM will never act on.
That noise eats your context window, degrades reasoning quality, and costs you money.
Related MCP server: claw-tsaver
โก The Solution
โ Without token-filter-mcp
Context fills up fast
LLM loses track of conversation
Paying for tokens it ignores
Sessions hit context limit early
Reads 14 lines to find 1 failure
โ With token-filter-mcp
Context stays lean
LLM maintains coherence longer
Only paying for useful tokens
Sessions last significantly longer
Reads exactly the failure, acts immediately
token-filter-mcp intercepts every tool output and applies intelligent, context-aware filtering โ returning only what the LLM actually needs to make decisions.
No configuration needed. No changes to your workflow. Just plug it in.
๐ฏ Real Results
Average savings across real-world tool outputs: 60-90% fewer tokens consumed
๐ง How It Works
flowchart LR
A[๐ค LLM Agent] -->|tool call| B[๐งน token-filter-mcp]
B -->|execute| C[๐ป System]
C -->|raw output| B
B -->|filtered output| A
style B fill:#7c3aed,stroke:#5b21b6,color:#fff
style A fill:#2563eb,stroke:#1d4ed8,color:#fff
style C fill:#059669,stroke:#047857,color:#fff1๏ธโฃ Detect โ Identifies what command was run (test runner? git? linter?)
2๏ธโฃ Execute โ Runs the command and captures full output
3๏ธโฃ Filter โ Applies the optimal strategy for that command type
4๏ธโฃ Verify โ Ensures no errors or actionable info was removed
5๏ธโฃ Return โ Sends compressed output to the LLM
๐จ Contextual Detection
The server doesn't blindly truncate. It understands what you ran and applies the right strategy:
It detects... | And does this... |
๐งช Test runners (jest, vitest, pytest, cargo test, go test) | Strips passing tests. Shows only failures with location + expected/received |
๐ | Converts to |
๐ | Removes repeated headers, keeps only hunks with ยฑ3 context |
๐ | One-liner: |
๐ Linters (tsc, eslint, biome, ruff) | Groups errors by rule/file, omits clean files |
๐ฆ Package installs | Returns |
โ Unknown commands | Conservative: deduplicate + truncate to 100 lines |
๐ก๏ธ Zero Information Loss
The #1 design principle: never hide an error.
โ
Lines matching error patterns (FAIL, Error:, TypeError, panic...) โ NEVER removed
โ
Non-zero exit codes โ full error output preserved
โ
Parser can't understand format โ returns raw output
โ
passthrough mode available for when you need everything๐ Installation
Add this to your MCP client config โ that's it:
{
"mcpServers": {
"token-filter": {
"command": "npx",
"args": ["-y", "token-filter-mcp"]
}
}
}npm install -g token-filter-mcp{
"mcpServers": {
"token-filter": {
"command": "token-filter-mcp"
}
}
}๐ Where does the config go?
Client | Config file |
Kiro |
|
Claude Desktop |
|
Cursor |
|
Any MCP client | Wherever it reads |
๐ง 7 Tools, One Purpose
{ "command": "npm test", "filter_level": "normal" }Level | Behavior |
| Smart filtering with sensible defaults |
| 50% additional reduction for tight context budgets |
| Raw output when you need everything (capped at 200KB) |
{ "path": "src/app.ts", "mode": "signatures" }Mode | What it returns |
| Content minus blank blocks, license headers, grouped imports |
| Only declarations โ no implementation bodies |
| Only sections matching |
Supports: TypeScript, JavaScript, Python, Rust, Go
{ "pattern": "useState", "path": "src", "group_by": "file", "max_results": 20 }Results grouped by file, deduplicated, with context lines. Uses ripgrep when available.
{ "command": "npm test" }All pass:
[PASS] 47/47 tests passed (3.2s)Failures:
[PASS] 44/47 tests passed
[FAIL] 3 failures:
1. src/auth.test.ts:42 โ "should refresh token"
Expected: 200
Received: 401
2. src/payments.test.ts:89 โ "should validate 3DS"
TypeError: Cannot read property 'status' of undefined
at processPayment (src/payments.ts:156)Auto-detects: Jest, Vitest, pytest, cargo test, go test
{ "operation": "status" }Operation | What you get |
|
|
| Only hunks with changes, no header spam |
|
|
|
|
|
|
|
|
{ "operation": "dump", "device": "emulator-5554" }Operation | What it does |
| Compact accessibility tree: resource-id, text, clickable, tap-center |
| Resolve |
| Tap raw coordinates (last resort, e.g. a map/canvas view) |
| Symbolic |
| Send text to the focused field |
| Swipe from |
| Long-press a locator ( |
| Install an APK from a local path / remove by package name |
| Recent logcat output pre-filtered to noteworthy lines (error/warning/fatal/assert level, plus known failure patterns) |
Replaces the "screenshot โ vision โ guess coordinates โ tap โ screenshot again" loop with cheap structured text.
{ "tool": "smart_git", "limit": 100 }Aggregates ~/.config/token-filter-mcp/metrics.jsonl (plus rotated history) into invocation count, raw vs filtered chars, overall savings %, and a per-tool breakdown sorted by chars saved โ without reading the JSONL file by hand.
โ๏ธ Configuration (Optional)
Works great out of the box. Customize only if you want to.
{
"defaults": {
"max_output_lines": 100,
"test_show_passes": false,
"git_log_max": 15,
"diff_context_lines": 3,
"dedup_threshold": 3
},
"commands": {
"my-custom-script.sh": { "filter_level": "passthrough" }
},
"metrics": { "enabled": true }
}Same schema. Project config overrides global. Global overrides built-in defaults.
๐ Built-in Observability
When enabled, every invocation is logged to ~/.config/token-filter-mcp/metrics.jsonl:
{
"tool": "smart_test",
"command": "npm test",
"rawChars": 5200,
"filteredChars": 480,
"savingsPercent": 90.7,
"strategy": "test_result_filter",
"filterDurationMs": 3,
"timestamp": "2026-06-30T15:30:00Z"
}Auto-rotated at 5MB, max 5 history files.
What it tracks:
Real savings per tool and command type
Which filters are most effective
Passthrough re-invocations (signal that a filter might be too aggressive)
Query it anytime with the metrics_summary tool instead of reading the JSONL by hand.
๐ก๏ธ Guarantees
Guarantee | Detail |
๐ Zero loss | Errors, test failures, and changes are never filtered out |
โก < 50ms overhead | Filtering adds negligible latency vs raw execution |
๐ช Safe fallback | Unknown commands get conservative treatment, not silence |
๐ No lock-in | Standard MCP protocol โ works with any compliant client |
๐ No network | Everything runs locally over stdio. Your code never leaves your machine |
๐ ๏ธ Development
git clone https://github.com/VMexicano/token-filter-mcp
cd token-filter-mcp
npm install
npm run build
npm test # 57 tests, all passingThe best token is the one you never spend.
Made with ๐ by Victor Mexicano
Available Tools
5 toolsfiltered_grepA
Search for regex patterns in a directory with results grouped by file or match, deduplicated with [รN] prefix. Uses ripgrep when available, falls back to native recursive search.
Inputs: path (required), pattern (required), exclude, include, +3 more.
filtered_readA
Read a file with intelligent reduction. Modes: "full" (collapses blanks, licenses, imports), "signatures" (extracts declarations only), "relevant" (focus pattern with ยฑ10 lines context).
Inputs: path (required), mode, focus, end_line, +1 more.
filtered_shellA
Execute a shell command with intelligent output filtering. Detects command type and applies the optimal filter strategy to reduce token consumption while preserving all actionable information (errors, failures, changes).
Inputs: command (required), cwd, timeout_ms, filter_level.
smart_gitA
Execute git operations with compact, optimized output. Supports: status (compact summary), diff (filtered hunks), log (one-line format), and action commands (commit/push/pull/add/branch with minimal confirmation).
Inputs: operation (required), cwd, args, filter_level.
smart_testA
Execute a test command and return structured, actionable output. Shows only failures by default (name, location, error, expected/received, truncated stack). Detects Jest/Vitest/pytest/cargo-test/go-test automatically.
Inputs: command (required), cwd, show_passes, filter_level, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 5 tools
Each tool targets a distinct operation: grep (search), read (file reading), shell (command execution), git (version control), test (test execution). No overlap in purpose.
Tools use two different prefixes: 'filtered_' for grep/read/shell and 'smart_' for git/test. While each group is internally consistent, the mix of prefixes reduces overall consistency.
With 5 tools, the server covers essential development operations without being bloated. Each tool serves a clear, non-redundant purpose.
The tool set covers search, reading, shell execution, git, and testingโcore developer tasks. Minor gaps like file writing or editing are acceptable given the focus on token-efficient inspection.
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Single-connection meta-router indexing 500+ MCP servers & A2A tools with 85% token compression and
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA meta-server that aggregates multiple MCP servers into a single interface, reducing token usage by 98%+ through progressive tool discovery and direct code execution that processes data between tools without consuming context window space.10Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that helps AI agents reduce token usage by compressing, summarizing, and managing conversation/context data more efficiently.11MIT
- AlicenseCqualityCmaintenanceAn MCP server that filters and compresses context by 80-90% before sending to an LLM, using code knowledge graphs and compression.2069 PyPI3MIT
- AlicenseAqualityDmaintenanceAn MCP server that reduces AI API costs by up to 97% through token measurement, compression, caching, and pruning, all without changing prompts.101Apache 2.0