mcp-snapshot-filter

mcp-snapshot-filter

MCP proxy that sits between Claude Code and chrome-devtools-mcp, intercepting content-heavy responses and applying smart filtering to reduce token usage by 40-60%.

Claude Code  <--stdio-->  mcp-snapshot-filter  <--stdio-->  chrome-devtools-mcp

Why?

Browser MCP tools (especially take_snapshot) return massive accessibility trees that fill up the context window fast. A single snapshot of a data-heavy page can be 30-40KB of text. This proxy transparently filters that down without breaking any tool interactions.

Real-world results: | Page | Original | Filtered | Reduction | |---|---|---|---| | GitHub repo page | 29.5KB | 22.8KB | 23% | | Portal with 36-row data table | 38.5KB | 17.3KB | 55% |

Setup

# Clone and build
git clone https://github.com/Akarda/mcp-snapshot-filter.git
cd mcp-snapshot-filter
npm install
npm run build

Add to ~/.claude.json (replace any existing chrome-devtools entry):

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/mcp-snapshot-filter/dist/index.js",
        "--filter-level=moderate",
        "--",
        "npx", "-y", "chrome-devtools-mcp@latest"
      ]
    }
  }
}

Restart Claude Code to pick up the new config.

Filter Levels

| Setting | Light | Moderate (default) | Aggressive | |---|---|---|---| | maxNodes | 1000 | 500 | 300 | | maxDepth | 20 | 15 | 10 | | maxSimilarSiblings | 5 | 3 | 2 | | Strip decorative nodes | yes | yes | yes | | Collapse navigation | no | yes | yes | | Focus main content only | no | no | yes | | Est. reduction | 20-30% | 40-60% | 60-80% |

Use --filter-level=off to disable all filtering and pass through raw responses.

What Gets Filtered

Snapshot filtering (biggest impact)

• Decorative nodes removed — role=none/presentation/separator, empty text nodes, unnamed generic wrappers are stripped (children promoted up)
• Similar siblings collapsed — after N consecutive siblings with the same role (e.g., 50 StaticText nodes in a table), keeps first N and shows ... [47 more StaticText elements collapsed]
• Navigation collapsed — navigation/banner/contentinfo/menu subtrees reduced to a single summary: [navigation: 21 items, 9 links]
• Main content focus (aggressive only) — when role=main exists, sibling subtrees are summarized
• Depth/node limits — prunes beyond maxDepth, caps total node count

Network request filtering

Strips image, font, stylesheet (and media in aggressive) entries from list_network_requests output. All xhr, fetch, document requests remain visible. get_network_request is never filtered — individual request details always pass through in full.

Console message filtering

Strips debug, verbose (and dir, trace at higher levels) from list_console_messages. Error and warning messages are always preserved.

Evaluate script & memory snapshot filtering

Large responses from evaluate_script and take_memory_snapshot are truncated:

• JSON arrays — kept to first N items (100/30/10 depending on level)
• HTML dumps — truncated at max text length
• Plain text — truncated at max text length (100KB/50KB/20KB depending on level)

What Is NOT Filtered

• Error responses — always passed through raw
• Image content blocks — screenshots etc. are never touched
• Unknown/new tools — only explicitly listed tools get filtered, everything else passes through
• Individual request/message details — get_network_request, get_console_message are unfiltered
• Non-interactive tools — emulate, performance_, screencast_, etc. pass through as-is

UID Integrity

All UIDs of visible nodes are preserved in filtered output. After taking a filtered snapshot, you can click, fill, or hover any UID shown in the output — the proxy forwards these calls to the upstream server unchanged.

Session Stats

Each filtered response includes a stats line: `` [cdp-filter-proxy: 20.7KB saved (55%) | session: 22.4KB saved across 2 calls (52%)] ``

How It Works

The proxy uses the MCP SDK's low-level Server class (not McpServer) to avoid JSON Schema to Zod conversion issues when proxying tool definitions. On startup it:

1. Spawns the upstream chrome-devtools-mcp as a subprocess via StdioClientTransport
2. Discovers all upstream tools via listTools()
3. Re-exposes them via setRequestHandler(ListToolsRequestSchema) and setRequestHandler(CallToolRequestSchema)
4. For calls to content-heavy tools, parses the response text into markdown sections (## Latest page snapshot, etc.), applies the appropriate filter to each section, and returns the filtered result

Compatibility with --slim mode

chrome-devtools-mcp supports a --slim flag that reduces the server to just 3 tools (navigate, evaluate, screenshot) for maximum token savings (~368 tokens). If the proxy detects --slim in the upstream args, it will warn that filtering has no effect — slim mode responses are already minimal. The proxy is designed for full mode where it preserves all tools while reducing response sizes by 40-60%.

Development

npm run build    # compile TypeScript to dist/

After rebuilding, restart Claude Code to pick up changes (MCP servers are long-lived processes).