peek-mcp 0.3.0

Let AI agents see your UI — point at elements, annotate, and get instant visual context for AI-powered code editing.

Peek

Point at your UI. Your AI agent sees it.

Why

AI coding agents can edit code, but they can't see your page. You end up describing layouts in words, copy-pasting HTML, or dragging screenshots into chat.

Peek fixes this. Your AI agent can screenshot any local page on its own. You can also point at specific elements with a bookmarklet, and the agent gets the screenshot plus element data (selectors, styles, bounding boxes).

Quick Start

Claude Code (CLI or VS Code) — recommended

pip install peek-mcp
peek setup

peek setup does everything for you: installs Playwright Chromium, registers Peek as an MCP server in Claude Code (user scope, all projects), opens the bookmarklet page in your browser. Just drag the blue button to your bookmark bar.

Other AI tools (Cursor / Windsurf / Claude Desktop)

pip install peek-mcp
playwright install chromium   # ~150 MB, one-time

Add to your MCP config file (e.g. .cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, or claude_desktop_config.json):

{
  "mcpServers": {
    "peek": {
      "command": "/absolute/path/to/peek",
      "args": ["mcp"]
    }
  }
}

Run which peek in your terminal to get the absolute path. Then visit http://localhost:8899 to grab the bookmarklet.

Recommended: tell your agent your dev port

Add this to your project's CLAUDE.md (or .cursorrules, etc.):

Dev server runs on http://localhost:3000

When using Peek's screenshot tool and you don't know the dev server URL, ask me which port the app is running on before taking a screenshot.

Replace 3000 with your actual port. This prevents your agent from guessing the wrong port.

Use it

Agent-driven screenshots (no bookmarklet needed):

Just ask your agent — "screenshot the page", "take a look at localhost:3000", "check if the button looks right". The agent calls screenshot(url) directly.

User-pointed captures (bookmarklet):

1. Run peek mcp (or let your AI tool start it via MCP)
2. Open http://localhost:8899, drag the blue button to your bookmark bar
3. Open your app, click the bookmarklet, pick a mode:

Mode	Shortcut	You do	Agent gets
Region	Alt+R	Drag a rectangle	Screenshot + elements in that area
Element	Alt+S	Click an element	Screenshot + selector, styles, HTML
Annotate	Alt+A	Draw (pen, box, arrow)	Screenshot + your drawings + elements

4. Tell your agent: "check what I just selected" — it calls get_latest_capture()

Supported URLs

Peek works with local and LAN addresses:

URL	Supported
http://localhost:3000	Yes
http://127.0.0.1:8080	Yes
http://0.0.0.0:5000	Yes
http://192.168.1.5:3000	Yes (LAN)
http://myapp.local:3000	Yes (.local domain)
http://myapp.test:8080	Yes (.test domain)
https://google.com	No (public URLs blocked)

MCP Tools

Tool	What it does
screenshot(url)	Takes a screenshot of a local/LAN URL
get_latest_capture()	Returns your latest bookmarklet selection — screenshot + element data + DOM context

For Element mode captures, the agent gets structural context to find the right code:

• ancestor chain (body > main > section.settings > div.flex)
• sibling position (2 of 3 <button> siblings)
• nearest heading (h2: Settings)
• parent layout (flex, row)

This means when you point at a button, the agent knows which button on which section — no guessing.

How It Works

Your AI agent calls screenshot(url)
    -> Playwright takes a headless screenshot
    -> Agent sees the page and can reason about the UI

You point at something with the bookmarklet
    -> Peek grabs element data + takes a Playwright screenshot
    -> Agent calls get_latest_capture() and sees everything
    -> "The chart legend overlaps the bars. Fixing the CSS..."

One process, two jobs: MCP server talks to your AI agent over stdio, bridge server receives bookmarklet data on port 8899. peek mcp runs both.

Troubleshooting

Playwright Chromium is not installed

Run playwright install chromium. This downloads the headless browser engine (~150 MB). Only needed once.

ERR_CONNECTION_REFUSED when taking a screenshot

Your dev server isn't running on that port. Start your dev server first, then ask the agent to screenshot. If you see this repeatedly, make sure the port in your CLAUDE.md matches your actual dev server.

Agent screenshots the wrong port

Add the CLAUDE.md snippet from step 3 above. Without it, the agent will guess.

Bookmarklet not working

Delete it from your bookmark bar and re-drag from http://localhost:8899. Make sure peek mcp is running.

peek: command not found after pip install

Your Python scripts directory may not be in your PATH. Try:

python -m peek mcp
# or find the path:
pip show peek-mcp | grep Location

Limitations

• Local/LAN only. Public URLs are blocked for security (SSRF prevention).
• No auth. Playwright uses a fresh browser context — no cookies, no login state.
• Captures may contain sensitive data. Passwords and hidden inputs are redacted, but visible text and screenshots are saved as-is to ~/.peek/captures/ (outside your project).

CLI

peek mcp                  # start everything (recommended)
peek mcp --port 9000      # different bridge port

Requirements

• Python 3.10+
• Playwright Chromium (playwright install chromium)