MCP Directory

How to add PageMap to Windsurf

Converts raw HTML into compressed, AI-readable page maps (97% token reduction) so agents can read and act on any web page. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 32★ · stdio · no auth

Windsurf config for PageMap

pip install retio-pagemap
{
  "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.

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the PageMap config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5PageMap's tools become available to Cascade.

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

What PageMap can do in Windsurf

get_page_map

Start here. Navigate to a URL and get a full structured map with numbered refs for every interactive element.

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.

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.

get_page_state

Check the current URL and title without a full rebuild. Use after actions that may navigate.

navigate_back

Go back one step in browser history.

Security

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the PageMap config there under the "mcpServers" key and restart the client.

Is PageMap safe to use with Windsurf?

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.

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).

View repo Full PageMap page