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:

Approach	Tokens	Extraction	What Your LLM Gets
Raw HTML (page.content())	~48,000	5ms	Full DOM tree — scripts, styles, hidden elements, ad markup. LLM drowns in noise and hallucinates clicks on invisible elements.
Vision (screenshot + OCR)	~8,000	~800ms	A pixel blob. LLM can "see" the page but can't target anything precisely. Clicks land 20px off. Forms fail.
Substrate	~1,000–4,000	~10–30ms	Structured JSON: what each element is, where it is, what state it's in. LLM clicks the right thing on the first try.

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:

Tool	What It Does
navigate	Load a URL, get back the page graph (capped at 400 elements)
click	Click any element by its numeric ID
type_text	Type into an input field (auto-clears first)
select_option	Pick a dropdown option by value
press_key	Press a keyboard key (Escape, Enter, Tab, arrows, modifiers)
scroll	Scroll up/down by 80% of viewport
screenshot	Get a visual snapshot + the graph together
go_back / go_forward	Browser history navigation
get_current_url	Check where you are

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.git
cd substrate-b
npm install
npx playwright install chromium
npm run build
npm start

License

MIT