Page-Map
Enables browser automation on Amazon pages through Page-Map's page outline, element finding, and interaction tools; Amazon home is used in the token benchmark.
Can be used with Figma in the browser, but as a canvas app it requires the screenshot fallback rather than DOM-based reading and control.
Provides browser-based interaction with GitHub pages, such as reading repo outlines and finding or clicking elements; GitHub tasks and repo pages are used in benchmarks.
Can be used with Google Sheets in the browser, but as a canvas app it requires the screenshot fallback rather than DOM-based reading and control.
Supports browser automation for Wikipedia search and reading tasks; Wikipedia search is used in benchmarks and recipe replay examples.
Enables browser automation on YouTube pages, including reading page structure and elements; YouTube home is used in the token benchmark.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Page-Map — open-source, low-cost browser control for AI agents
Page-Map lets any AI agent — Claude Code, Cursor, Codex, VS Code, any MCP client — read and control your real Chrome through the page's structure instead of screenshots. It is free, runs locally, needs no API key, and several agents can work in parallel tabs.
Looking for a cheaper alternative to screenshot-based computer use or browser agents, a multi-agent browser tool, or zero-cost replay of repeated browser tasks? That's what this is.
Same 5 real tasks, same Chrome | Page-Map | Screenshot + pixel-click loop |
Success | 15/15 | 12/15 (fails dropdowns) |
Cost | $0.40 | $1.27 (3.2× more) |
Time | 132 s | 246 s (1.9× slower) |
5 tasks in parallel | 13.4 s | not possible (needs the one visible tab) |
Repeating a task | $0, < 3 s (recipe replay) | full price every time |
Measured with scripts/compare.js (Claude via claude -p, 3 runs per task, answers checked against live sources). Reproduce it yourself.
AI agent ──MCP──► mcp/server.js ──private socket──► native host ──native messaging──► extension ──► your tabsThe agent is the brain; Page-Map is its eyes and hands. Scripts do everything deterministic; the agent only decides.
Install (macOS / Linux, Chrome)
git clone https://github.com/xlucifer65/page-map.git && cd page-map
npm install
npm run install-host # registers the native host with Chrome
npm run install-host -- --browser brave # or chromium | edge | all (default: chrome)Chrome →
chrome://extensions→ Developer mode → Load unpacked → pick./extension(or unzip the latest release). The manifestkeypins the id tohmoipddaijkfcidjilmbbiodbmgedbjm.Add the MCP server to your agent:
Agent
Command / config
Claude Code
claude mcp add -s user page-map -- node "$PWD/mcp/server.js"Cursor / VS Code / others
MCP server, stdio: command
node, args["<repo>/mcp/server.js"]Ask your agent: "Open news.ycombinator.com and tell me the top story."
Windows isn't supported yet (needs a registry-based host install) — PRs welcome.
Related MCP server: chrome-browser-bridge
Tools
tool | what it does |
| opens a page; returns its outline + text preview + |
| title, landmarks, headings with refs, element counts, ~700-char text preview |
| main content as markdown; |
| best matching elements with refs |
| interactive elements on screen: |
| by ref or label ( |
| fills text fields, dropdowns (native and custom) and checkboxes by label in one call |
| several steps in one call; stops at the first failing step |
| save a finished task as label-based steps; replay with new values, step-checked |
| tabs; image for canvas apps; token/latency metrics |
Generic skills run automatically: cookie banners / consent walls / newsletter popups are closed (preferring "Reject all"), custom dropdowns are opened and picked, secrets are never read.
Recipes & site memory live in ~/.page-map/recipes.json (never in the agent's context). Replay with zero
model tokens: node scripts/recipe.js run signup-form --"Full name"="Alan Turing".
Parallel agents: every MCP server gets its own socket in ~/.page-map/sessions/; the native host routes
replies to the session that asked, and each session sticks to its own tab.
Refs carry a random 4-letter prefix per page load (kqxa), so a ref from a previous page is rejected rather than clicking
something else. Example read_page output:
Fixture Shop — http://127.0.0.1:5173/shop.html
kqxa3 link "Home"
kqxa4 link "Second page"
kqxa8 textbox "Search products" ="knives"
kqxa9 button "Search"
kqxa11 combobox "Country" ="Germany"
kqxa13 password "Password" ="<secret>" [secret]
… 1 more off-screen (scroll or viewport_only=false)Benchmark (npm run bench)
Estimated tokens (chars/4) on real pages, 1280×800, vs. one screenshot ≈ 1,365 tokens:
page | find | outline | viewport | full page | raw HTML |
GitHub repo page | 38 | 363 | 1,024 | 2,921 | 116,339 |
Hacker News | 0* | 23 | 975 | 1,466 | 8,505 |
Amazon home | 63 | 217 | 795 | 2,040 | 337,773 |
YouTube home | 38 | 54 | 276 | 277 | 300,893 |
*no "search" element on HN. All views computed in < 15 ms. The real saving comes from find + outline + diffs
replacing a screenshot on every step.
Head-to-head vs. screenshots (node scripts/compare.js --runs 3 --parallel)
Same 5 real tasks (GitHub, Hacker News, Wikipedia search, MDN, a signup form), same Chrome, Claude via claude -p,
3 runs each. "Screenshots" = classic screenshot + pixel-click loop. Answers checked automatically against live sources.
Page-Map (structure) | Screenshots | |
Success | 15/15 | 12/15 (fails native dropdowns) |
Cost | $0.40 | $1.27 (3.2×) |
Time | 132 s | 246 s (1.9×) |
Turns | 45 | 157 |
All 5 tasks in parallel | 13.4 s wall | not possible (needs the one visible tab) |
Recipes (learn once, replay with new values):
learn | agent replay |
| |
Wikipedia search | $0.045 · 13 s | $0.033 · 11.5 s | $0 · 0.8 s |
Signup form | $0.026 · 11 s | $0.022 · 9 s | $0 · 3 s |
Safety
Password, card/CSC, one-time-code, PIN, API-key/token field values — and any Luhn-valid card number — are never read (
<secret>);typerefuses secret fields unlessallow_secret=true.Blocklist (email, messaging, payments, banks, password managers by default; plain patterns cover subdomains) — checked in the service worker and against the page's real URL in the content script, so redirects can't slip through. Blocked tabs show only their host in
list_tabs. Edit in the extension's Options page; agents can't change it.Every result and every extension error is prefixed with a marker telling the agent that page text is untrusted data, not instructions.
Local only: unix socket
~/.page-map/pagemap.sock(0600 in a 0700 dir). No TCP port, no network calls.
Tests
npm test # unit: DOM core (jsdom), native framing, MCP server with a fake extension
npm run test:e2e # real Chromium + extension + native host + MCP server
npm run bench # token benchmark on live sitesCHECKLIST.md lists every requirement and the test that proves it. .claude/agents/page-map-monitor.md
is an independent auditor agent that re-checks the whole checklist.
Contributing
Issues, site reports and PRs are welcome — from people and from coding agents. See CONTRIBUTING.md and AGENTS.md. Security reports: SECURITY.md (please report privately).
Page-Map is an independent community project. It is not affiliated with or endorsed by Anthropic, Google, or any browser or AI vendor.
Limits / next
Main frame only (no iframes yet); closed shadow roots and canvas apps (Google Sheets, Figma) need
screenshot.One MCP server and one browser at a time: a second server or a second Chrome profile gets a clear refusal.
Any process running as your user could impersonate the server socket while no server runs — same trust level as your Chrome profile files.
The host wrapper pins the node binary path; re-run
npm run install-hostafter upgrading node.type(submit=true)skips form submit when the pagepreventDefaults Enter itself; pages that handle Enter without that may submit twice.Huge pages (>60k nodes): only
read_pagesays the scan was cut short.Default blocklist is host-based, so
icloud.comandwise.comare blocked whole (incl. non-sensitive parts). Card-number masking also hides IMEIs (also Luhn-valid).Next: recipes (record/replay per-site action sequences = 0 tokens), image semantics (dominant color, OCR, CLIP), Chrome built-in AI labeling.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Cloud browsers for AI agents: saved logins, residential IPs, live human takeover, 57 browser tools.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents and developers to automate real Chrome/Chromium browsers through the Chrome DevTools Protocol, with token-efficient snapshots, multi-action batching, shadow DOM traversal, system-page control, extension management, and network/WebSocket inspection.811MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control a real, authenticated Chrome browser through native tools for navigation, DOM interaction, form filling, scraping, screenshots, and human-in-the-loop checkpoints while minimizing tokens and latency.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to browse and interact with web pages through a token-efficient, structured page representation — orientation summaries, targeted element queries, and full detail only on request — instead of raw accessibility-tree dumps. Supports navigation, interaction, forms, screenshots, console and network monitoring, session/tab management, and browser-based development auditing.4 npm-
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to browse and interact with web pages through structured, token-efficient representations instead of full accessibility-tree dumps, returning compact page orientations, targeted element queries, and detail on demand. Agents can navigate, click, type, fill forms, manage tabs and sessions, and inspect console or network activity at a fraction of the usual context cost.4 npmMIT