# Retio-ai/pagemap [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/Retio-ai/Retio-pagemap  
**GitHub Stars:** 36  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/retio-ai-pagemap

## Description
Compresses 100K-token HTML into 2-5K-token structured maps while preserving every actionable element. AI agents can read and interact with any web page at 97% fewer tokens.

## Tools
Capabilities this server exposes over MCP:

- **get_page_map** — Start here.** Navigate to a URL and get a full structured map with numbered refs.
- **execute_action** — Click, type, select, or hover using a ref number from the last `get_page_map`.
- **fill_form** — Fill multiple form fields in one call. More efficient than sequential `execute_action` calls.
- **get_page_state** — Check current URL and title without a full rebuild. Use after actions that may navigate.
- **scroll_page** — Scroll to reveal lazy-loaded content before calling `get_page_map` again.
- **wait_for** — Wait for dynamic content to appear (e.g. after a search or form submit).
- **take_screenshot** — Capture the visual state when the PageMap alone is ambiguous.
- **navigate_back** — Go back one step in browser history.
- **open_tab** — Open a new browser tab and navigate to a URL.
- **switch_tab** — Switch to a different open tab by index.
- **list_tabs** — List all open tabs with their URLs and titles.
- **close_tab** — Close a tab by index.
- **batch_get_page_map** — Fetch multiple URLs in parallel. Use for comparison tasks.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "pagemap": {
    "command": "uvx",
    "args": ["retio-pagemap"]
  }
}
```

## Documentation

## What Retio-ai/pagemap does

Retio-ai/pagemap is a Browser Automation server that uses Chromium to give MCP clients a compact representation of web pages. Instead of returning the full HTML, it builds structured maps generally sized at 2–5K tokens from pages that may contain 100K or more tokens of markup. Maps include numbered references that agents can use for subsequent actions.

The Retio-ai/pagemap MCP server supports 16 detected page types, including product pages, search results, articles, forms, checkouts, dashboards, documentation, and error pages. It also provides structured e-commerce data such as prices, options, ratings, availability, descriptions, and images. Built-in coverage includes more than 30 named e-commerce sites, including Amazon, eBay, Walmart, Nike, Coupang, ZOZO, Tmall, and Taobao.

## How it works

Start with `get_page_map` to navigate to a URL and obtain the current page structure. Use the returned reference numbers with `execute_action` to click, type, select, or hover. `fill_form` handles several fields in one request, while `scroll_page` and `wait_for` help expose lazy-loaded or delayed content. After an action that may change the page, `get_page_state` reports the current URL and title without rebuilding the complete map.

The server maintains browser sessions and supports multiple tabs through `open_tab`, `switch_tab`, `list_tabs`, and `close_tab`. `navigate_back` moves through browser history, and `batch_get_page_map` retrieves several URLs in parallel. Screenshots are available when the structured map does not provide enough visual context.

PageMap includes handling for cookie consent dialogs, promotional overlays, login barriers, bot-detection pages, and stale references. It can identify several common CAPTCHA and bot-protection providers and report barriers with suggested next steps. Content is treated as untrusted input, with SSRF controls, prompt-injection defenses, resource limits, robots.txt compliance, and isolated session storage.

## Setup and configuration

Install the Python package with `pip install retio-pagemap`. The local MCP process can run through `uvx retio-pagemap`, and Chromium is installed automatically on first use. Python 3.11 or newer is required. If automatic browser installation fails, Chromium can be installed manually with `playwright install chromium`.

The Retio-ai/pagemap MCP server runs in STDIO mode by default. Docker is also supported through the published image, using HTTP transport with a command such as `docker run -p 8000:8000 retio1001/pagemap --transport http`. For Claude Desktop on macOS, the configuration may need an absolute path to `uvx`; VS Code uses `servers` rather than `mcpServers` in its MCP configuration file.

Private IP addresses are blocked by default. Local targets require the `--allow-local` option or `PAGEMAP_ALLOW_LOCAL=1`.

## Tools and capabilities

- Build compact page maps with numbered interactable references.
- Click, type, select, hover, and fill multiple form fields.
- Scroll, wait for dynamic content, inspect page state, and capture screenshots.
- Open, switch, list, and close tabs, or navigate backward.
- Fetch page maps for multiple URLs in parallel.
- Extract supported metadata and JSON-LD types, including products, articles, videos, FAQs, events, local businesses, breadcrumbs, and item lists.
- Produce agent-oriented text, JSON, or optional delta evidence packets through the Python API.

## Limitations and notes

The first browser navigation can take roughly 10–30 seconds while Chromium starts; later pages are expected to load faster. The server does not bypass website access controls, and users remain responsible for complying with target-site terms and applicable law. Localhost and other private targets need explicit permission. The package is licensed under AGPL-3.0.

_Full upstream README: https://allmcps.com/mcp/retio-ai-pagemap/readme_