PageMap
Converts raw HTML into compressed, AI-readable page maps (97% token reduction) so agents can read and act on any web page.
Add to your client
Copy the config for your MCP client and paste it into its config file.
pip install retio-pagemapPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"pagemap": {
"command": "uvx",
"args": [
"retio-pagemap"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.11+
- Chromium (auto-installed on first use; can be installed manually via 'playwright install chromium')
- uvx (or pip) to launch the server
About PageMap
PageMap is an MCP server that compresses raw HTML web pages into structured, AI-readable maps (typically 2-5K tokens vs 100K+ raw), letting agents read page content and interact with it — click, type, select, hover, manage tabs, and navigate — using stable numbered element refs. It auto-detects 16 page types, has deep extraction for 30+ e-commerce sites, and includes barrier/bot detection plus SSRF and prompt-injection defenses. Local STDIO mode is free and open source under AGPL-3.0; a hosted Cloud API with auth and billing is available separately.
Tools & capabilities (13)
get_page_mapStart here. Navigate to a URL and get a full structured map with numbered refs for every interactive element.
execute_actionClick, type, select, or hover using a ref number from the last get_page_map.
fill_formFill multiple form fields in one call — more efficient than sequential execute_action calls.
scroll_pageScroll to reveal lazy-loaded content before calling get_page_map again.
wait_forWait for dynamic content to appear (e.g. after a search or form submit).
take_screenshotCapture the visual state when the PageMap alone is ambiguous.
get_page_stateCheck the current URL and title without a full rebuild. Use after actions that may navigate.
navigate_backGo back one step in browser history.
batch_get_page_mapFetch multiple URLs in parallel. Use for comparison tasks.
open_tabOpen a new browser tab and navigate to a URL.
switch_tabSwitch to a different open tab by index.
list_tabsList all open tabs with their URLs and titles.
close_tabClose a tab by index.
What this server can do
PageMap provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Give an AI agent compressed, actionable 'eyes and hands' on arbitrary web pages without overflowing the context window.
- Run multi-page browsing sessions (search, filter, navigate) that would break read-only or raw-snapshot tools after a few pages.
- Extract structured product data (price, size/color options, ratings, availability) from 30+ major e-commerce sites.
- Automate web interactions — clicking buttons, filling forms, selecting options — while handling cookie consent, popups, and login/bot barriers.
- Compare items or pages by fetching multiple URLs in parallel with batch_get_page_map.
Security notes
Treats all web content as untrusted: SSRF defense, prompt-injection defense (content boundaries, role-prefix stripping, suspicious-content flagging), RFC 9309 robots.txt compliance (opt out with --ignore-robots), DOM/HTML/response size guards, and per-session cookie/storage isolation. Private/local IPs are blocked by default — enable with --allow-local or PAGEMAP_ALLOW_LOCAL=1. Users are responsible for complying with target sites' terms of service and applicable law.
PageMap FAQ
How is PageMap different from Playwright MCP, Firecrawl, or Jina Reader?
PageMap produces a far smaller, interaction-capable map (2-5K tokens per page) and supports unlimited multi-page sessions, while Playwright MCP dumps large accessibility snapshots that overflow context after 2-3 pages and Firecrawl/Jina are read-only markdown converters.
Do I need to install a browser manually?
No. Chromium is auto-installed on first use. If it isn't found, run 'pip install retio-pagemap && playwright install chromium' to install it manually.
Can it run over HTTP instead of STDIO?
Yes. The default is local STDIO, but a Docker image runs an HTTP server: 'docker run -p 8000:8000 retio1001/pagemap --transport http' (multi-arch amd64/arm64 images on Docker Hub and GHCR).
Why does 'spawn uvx ENOENT' happen on Claude Desktop (macOS)?
Claude Desktop does not inherit your shell PATH. Run 'which uvx' and use the absolute path (e.g. /opt/homebrew/bin/uvx) in your config.
Can it access localhost or private networks?
Private/local IPs are blocked by default for SSRF protection. Use the --allow-local flag or set PAGEMAP_ALLOW_LOCAL=1 to opt in.
Is it free?
Local STDIO mode is free forever and open source under AGPL-3.0. A hosted multi-tenant Cloud API with auth, rate limiting, and credit-based billing is available by contacting retio1001@retio.ai.
Alternatives to PageMap
Compare all alternatives →
Automate your existing browser with AI using your real profile, logged-in sessions, and stealth fingerprint.
All-in-one web access MCP — Web Unlocker, SERP, Scraper API, and a cloud Scraping Browser.
macOS screen capture, AI visual analysis, and full GUI automation for AI agents.
Compare PageMap with: