The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Substrate Browser listing page.
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.
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:
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.
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.
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.
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonsubstrate-browser server to the mcpServers block:(Note: Playwright will automatically download the Chromium binary on the very first run. This requires Node.js 20+ installed on your system).
If you want to modify the extraction logic or add your own tools:
MIT