Smart DOM MCP Server

Token-efficient browser automation for AI agents. Drop-in alternative to Playwright MCP that filters the DOM before returning it — only interactive elements, grouped by page section.

Why?

Playwright MCP sends the full accessibility tree on every interaction. On complex pages, that's 10-40K tokens per snapshot. Your 128K context fills up after ~3-12 actions.

Smart DOM filters to only interactive elements (buttons, links, inputs, selects, dialogs) and caps output at 30 elements per section with dedup. Result: 3-13x fewer tokens.

Site	Playwright MCP	Smart DOM	Reduction
Amazon	~37K tokens	~3.2K tokens	11x
Hacker News	~10K tokens	~757 tokens	13x
GitHub	~10K tokens	~2.5K tokens	4x
Wikipedia	~8.4K tokens	~2.6K tokens	3.3x

Actions in 128K context window:

• Amazon: 3 (Playwright) → 39 (Smart DOM)
• Hacker News: 12 → 169

Install

git clone https://github.com/Frontrunner0x/smart-dom-mcp.git
cd smart-dom-mcp
npm install
npx playwright install chromium

Setup

Claude Code

claude mcp add smart-dom -s user -- node /path/to/smart-dom-mcp/src/index.js

Claude Desktop / Cursor / etc.

Add to your MCP config:

{
  "mcpServers": {
    "smart-dom": {
      "command": "node",
      "args": ["/path/to/smart-dom-mcp/src/index.js"]
    }
  }
}

Tools

navigate

Open a URL and get filtered interactive elements grouped by page section.

navigate({ url: "https://github.com" })
→ { sections: { header: [...], main: [...] }, totalShown: 90 }

dom_summary

Re-scan current page for interactive elements. Use focus to get only one section.

dom_summary({ focus: "main" })
→ { section: "main", elements: [...], count: 28 }

dom_act

Click, type, select, check/uncheck elements by their ref (from navigate/dom_summary).

dom_act({ ref: "@e5", action: "click" })
→ { ok: true, action: "clicked", label: "Sign in" }

dom_act({ ref: "@e12", action: "type", value: "hello world" })
→ { ok: true, action: "typed", value: "hello world" }

dom_read

Extract readable content: tables, headings, alerts, form values, or plain text.

dom_read({ selector: "main" })
→ { headings: [...], tables: [...], text: "..." }

screenshot

Visual fallback. Capture viewport, full page, or a specific element.

screenshot({ fullPage: true })
screenshot({ selector: "#results" })

wait

Wait for text to appear, disappear, or a fixed delay.

wait({ text: "Results loaded" })
wait({ seconds: 2 })

How it works

1. Persistent Chromium session — browser stays open across tool calls (no cold start per action)
2. DOM filter — querySelectorAll for interactive elements only, grouped by ARIA landmarks (header, nav, main, sidebar, footer, dialog)
3. Dedup + cap — identical label+role combos are deduplicated, max 30 elements per section
4. Ref system — each element gets a stable ref (@e0, @e1, ...) for use with dom_act
5. Playwright actions — dom_act uses Playwright's native click/fill/selectOption for reliability with SPAs

Limitations

• Headless only — no access to your logged-in browser sessions (use Chrome DevTools MCP for that)
• No iframe support — elements inside iframes are not captured (planned)
• No shadow DOM — web components with shadow roots are not traversed (planned)
• Single tab — one page at a time

License

MIT