Substrate Browser

Substrate

Stop wasting 48K tokens to read a webpage. Substrate compresses a typical content page into roughly 1–4K tokens your LLM can actually use — vs. ~48K of raw HTML.

Substrate is an MCP server that gives your AI agent eyes and hands on the web. It extracts a compressed semantic graph of any webpage — buttons, inputs, links, dropdowns, checkboxes — with precise pixel coordinates, and handles clicking, typing, and selection via spatial coordinates. No CSS selectors. No xpaths. No hallucination.

Why It Matters

Every other browser automation approach burns tokens on noise:

The math: a ~110-element content page (say, Wikipedia) compresses to roughly ~2,300 tokens — about 1.8% of a typical 128K context window. You can fit roughly ~55 page extractions before the LLM runs out of room. With raw HTML, you get 2.

Token figures are order-of-magnitude, measured live on representative pages (example.com ~84 tok, Wikipedia ~3.5K, Hacker News front page ~4.4K, extraction 8–58ms). They scale with page density; the extractor caps output at MAX_ELEMENTS=400, so very dense pages are truncated rather than emitted in full. The math is arithmetic: on a ~2.3K-token page, ⌊128K/2.3K⌋ ≈ 55 extractions.

The real win — shorter action loops:

Without Substrate:                          With Substrate:navigate → screenshot                       navigate→ "I see a button" → click (wrong)          → {btn id=3 "Submit" [640,400]}→ screenshot → "ah, more right"             → click(3) → done.→ click → "not that either"                 → screenshot → ...                          2 tool calls. Task complete.8-12 tool calls. Task complete.

That's not a marginal improvement. That's 5-6x fewer API calls, 5-6x less latency, and 5-6x lower cost per web task.

How It Works

Substrate runs as a headless Chromium browser via the Model Context Protocol (MCP). Your LLM agent talks to it through 10 simple tools:

Every navigation and interaction tool returns the same compressed graph (get_current_url returns just the URL; screenshot returns the image plus the graph). Your LLM reads the graph, picks an element ID, and calls the next tool. No image interpretation. No HTML parsing. Just IDs and coordinates.

Installation & Setup

Substrate is a standalone Model Context Protocol (MCP) server. You do not need to write code to use it — you just plug it into your AI assistant.

Option 1: Claude Desktop (Recommended)

1. Open your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the substrate-browser server to the mcpServers block:

{  "mcpServers": {    "substrate-browser": {      "command": "npx",      "args": ["-y", "substrate-browser"]    }  }}

3. Restart Claude Desktop. You will now see the 10 browser tools available (a small hammer icon) and you can ask Claude to "Go to example.com and tell me what you see".

(Note: Playwright will automatically download the Chromium binary on the very first run. This requires Node.js 20+ installed on your system).

Option 2: Running from Source (For Developers)

If you want to modify the extraction logic or add your own tools:

git clone https://github.com/manuelinuxkr/substrate-b.gitcd substrate-bnpm installnpx playwright install chromiumnpm run buildnpm start

License

MIT