Chrome Local MCP

Give Claude Code full control over a real Chrome browser.

Navigate pages, click elements, fill forms, take screenshots, extract text — all locally, no cloud needed.

Install in 10 seconds

claude plugin marketplace add callmehuyv/claude-plugins-marketplace
claude plugin install chrome-local-mcp@callmehuyv-plugins

Restart Claude Code. Done. The mcp__chrome_local__* tools are ready.

That's it. No global install, no config files, no browser flags.

What can it do?

Just talk to Claude Code naturally:

> Open Chrome and go to github.com
> Take a snapshot of the page
> Click the "Sign in" button
> Fill in the username field with "myuser"
> Take a screenshot with OCR
> Get all the links on this page

Claude Code picks the right MCP tool automatically.

Why Chrome Local MCP?

Most browser MCPs (Playwright MCP, Chrome DevTools MCP) are built for general-purpose automation. Chrome Local MCP is built for how Claude Code actually works — fast, token-efficient, and practical.

| | Chrome Local MCP | Playwright MCP | Chrome DevTools MCP | |---|:---:|:---:|:---:| | Persistent sessions (stays logged in) | Yes | No | No | | Accessibility snapshots (no vision tokens) | Yes | Yes | No | | Element refs for reliable clicking | Yes | Yes | No | | Local OCR via Apple Vision (zero cost) | Yes | No | No | | Batch actions in a single tool call | Yes | No | No | | Visible browser (see what Claude does) | Yes | Configurable | Yes | | Works with your real Chrome profile | Yes | No | Partial | | REST API for external integrations | Yes | No | No | | Zero config — just install and go | Yes | Yes | Requires flags |

Highlights

• Persistent browser profile — Log into a site once, Claude can access it every time. No re-authentication between sessions.
• Local OCR saves tokens — Extract text from screenshots locally using Apple Vision. Saves 2,000-5,000 vision tokens per screenshot.
• Batch actions — Chain click, type, scroll, navigate in a single tool call. Fewer round trips, faster workflows.
• Real Chrome — Not a sandboxed test browser. Extensions, profiles, and site compatibility just work.
• Simple architecture — One file, stdio transport, no sidecar processes, no browser extensions. Just works.

Installation Options

Option A: Claude Code Plugin (Recommended)

claude plugin marketplace add callmehuyv/claude-plugins-marketplace
claude plugin install chrome-local-mcp@callmehuyv-plugins

Two commands. Auto-registered. You're done.

Option B: npx (no global install)

claude mcp add chrome_local -- npx chrome-local-mcp@latest

Option C: Global install

npm install -g chrome-local-mcp
claude mcp add --scope user chrome_local chrome-local-mcp

Option D: From source

git clone https://github.com/callmehuyv/chrome-local-mcp.git
cd chrome-local-mcp
npm install
claude mcp add --scope user chrome_local node /path/to/chrome-local-mcp/mcp-server.js

After any install method, restart Claude Code to pick up the new tools.

Available Tools (22)

| Tool | What it does | |------|-------------| | launch | Launch Chrome (visible or headless) | | close_browser | Close the browser | | new_tab | Open a new tab | | list_pages | List all open tabs | | navigate | Go to a URL | | go_back | Go back in history | | snapshot | Get accessibility tree with element refs (cheapest way to read a page) | | click | Click by selector, text, or coordinates | | click_ref | Click an element by its snapshot ref | | type | Type text into an input | | type_ref | Type into an element by its snapshot ref | | press_key | Press a keyboard key (Enter, Tab, Escape, etc.) | | select | Select a dropdown option | | scroll | Scroll the page | | screenshot | Take a screenshot (with optional local OCR) | | ocr | Extract text from any image file via Apple Vision | | get_text | Get text content of the page or element | | get_links | Get all links on the page | | get_inputs | Get all form inputs | | eval | Execute JavaScript on the page | | wait_for | Wait for an element to appear | | batch | Run multiple actions in a single tool call |

Accessibility Snapshots — Your Secret Weapon

The snapshot tool is the cheapest and fastest way to understand a page. No screenshots, no vision tokens, no OCR. Just a structured text tree:

> Take a snapshot of the page

- RootWebArea "Example Domain"
  - heading "Example Domain"
  - StaticText "This domain is for use in..."
  - link "Learn more" [ref=e1]

Each interactive element gets a ref (e.g. [ref=e1]). Use it to click or type:

> Click ref e1
> Type "hello" into ref e3

Cost comparison

| Method | Token cost | Speed | |--------|-----------|-------| | snapshot | ~100-500 text tokens | Instant | | screenshot with ocr: true | ~500-2,000 text tokens | ~1.4s | | screenshot (image) | ~2,000-5,000 vision tokens | Instant |

Always try snapshot first. Use screenshots only when you need visual context.

Local OCR (macOS)

Extract text from screenshots locally — no tokens spent sending images to Claude:

> Take a screenshot with OCR
> OCR this image: /tmp/my-image.png

Requirements:

• macOS (uses Apple Vision framework)
• Python 3 with:

  pip3 install pyobjc-framework-Vision pyobjc-framework-Quartz

How It Works

Claude Code  ←— stdio —→  MCP Server  ←———→  Puppeteer  ←———→  Chrome

1. Claude Code sends tool calls via MCP protocol (stdio)
2. mcp-server.js translates them into Puppeteer commands
3. Puppeteer controls a local Chrome instance
4. Chrome opens in visible mode so you can see what's happening

REST API (Optional)

An HTTP API server is included for programmatic control outside Claude Code:

npm run server   # starts on http://localhost:3033

curl -X POST http://localhost:3033/launch
curl -X POST http://localhost:3033/navigate \
  -H 'Content-Type: application/json' \
  -d '{"pageId": 1, "url": "https://example.com"}'
curl -X POST http://localhost:3033/screenshot \
  -H 'Content-Type: application/json' \
  -d '{"pageId": 1}'

See server.js for all endpoints.

Configuration

Headless mode

> Launch Chrome in headless mode

Window size

Default: 1440x900. Edit mcp-server.js to change the --window-size arg.

Requirements

• Node.js 18+
• Chrome/Chromium (Puppeteer downloads one automatically if needed)
• Claude Code CLI

Troubleshooting

MCP tools not showing up?

1. Check registration: claude mcp list
2. Restart Claude Code (new session)
3. Verify the path points to the correct mcp-server.js

Browser not launching?

• Close any other Puppeteer/Chrome automation instances
• Run npm install to re-download Chrome
• macOS: Allow Chrome in System Preferences > Privacy & Security

Screenshots not returning images?

• Use a Claude Code model that supports images
• Screenshots save to /tmp/ — check the file path in the response

Contributing

Found a bug or have a feature request? Open an issue — we'd love to hear from you.

If this project helps you, consider giving it a star — it helps others discover it too.

License

MIT