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.

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)

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

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