claude-has-hands
Provides tools to drive and inspect the user's existing, signed-in Google Chrome browser through a local bridge, including navigation and tabs, DOM/accessibility inspection, clicking, typing, scrolling, key presses, screenshots, console and network capture, waits, file upload, JavaScript evaluation, and batches.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
claude-has-hands
A guarded local bridge that lets AI coding CLIs drive your existing, signed-in Chrome. A Chrome MV3 extension and a native messaging host expose one set of browser_* tools over MCP (stdio and HTTP), a localhost REST API and a chh shell command, so Claude Code, Codex, Gemini CLI or any tool that can run a shell command can use the same browser.
Why
Browser automation frameworks start a fresh browser with no sessions, and sites with MFA or device trust block them. This project goes the other way. It works inside the browser you already use, with its cookies, extensions and device trust, and it never asks the agent for credentials. Signing in and passing MFA stay human steps: the agent waits while you do them.
The bridge is a local tool for one user. It is not a cloud browser service and not a test framework.
Related MCP server: browserpilot-mcp
Architecture
Chrome (your profile) Native host (Node, spawned by Chrome)
┌─────────────────────────┐ native ┌──────────────────────────────────────┐
│ MV3 extension │ messaging │ dispatcher (request/response match) │
│ - CDP via chrome.debugger ◀──────────────▶ │ tool registry (zod schemas) │
│ - DOM + MAIN-world capture│ (stdio) │ │
└─────────────────────────┘ │ Unix socket REST 127.0.0.1:<port> │
│ bridge.sock Bearer token │
└───────┬──────────────┬───────────────┘
│ │
mcp-server.js│ ┌────────┴─────────┬──────────────┐
(direct MCP) │ │ mcp-adapter.js │ chh CLI │
│ │ MCP over stdio │ curl wrapper │
│ │ or HTTP │ │
▼ ▼ ▼ ▼
Claude Code Codex, Gemini, shell toolsextension/is the MV3 extension. Its service worker keeps the native host alive and runs each command through the Chrome DevTools Protocol and content scripts.native-host/src/dispatcher.tsis the single command router.tool-registry.tsis the single source of truth for tool names, zod input schemas and result formatting. Every transport reads from it.native-host/src/rest-server.tsis the localhost REST API (GET /v1/status,GET /v1/tools,POST /v1/call).native-host/src/mcp-adapter.tsis an MCP server that forwards each tool call to the REST API.mcp-server.jsis the older path that talks to the Unix socket directly.bin/chhis a shell wrapper around the REST API for agents without MCP.
Install
Requirements: Google Chrome on macOS or Linux, Node.js 22.18 or later (the unit tests run TypeScript natively), npm. The chh CLI also needs curl and python3.
git clone https://github.com/isaacasamoah/claude-has-hands.git
cd claude-has-hands
npm ci
npm run buildOpen
chrome://extensions, enable Developer mode and choose Load unpacked. Select theextension/directory (notextension/dist/).Copy the extension ID and run
./scripts/install.sh <extension-id>. It builds the project, writes a launcher that records the absolute path of your Node binary (Chrome starts native hosts with a minimalPATH) and registers the native messaging host for that extension ID.Reload the extension. Chrome starts the native host, which writes
bridge.jsonand a freshbridge.tokenunder~/.claude/claude-has-hands/.
Connect an agent
Use the absolute path of this checkout in place of <repo>. Chrome and the extension must be running.
# Claude Code
claude mcp add claude-has-hands -- node <repo>/native-host/dist/mcp-adapter.js
# Codex
codex mcp add claude-has-hands -- node <repo>/native-host/dist/mcp-adapter.js
# Gemini CLI
gemini mcp add claude-has-hands node <repo>/native-host/dist/mcp-adapter.jsThe adapter reads bridge.json and the token on every call, so it keeps working when the host restarts on a new port with a new token.
For any agent with a shell tool, use the CLI:
<repo>/bin/chh status
<repo>/bin/chh tools
<repo>/bin/chh call browser_navigate '{"url":"https://example.com"}'
<repo>/bin/chh call browser_survey '{}'./scripts/install-cli.sh links chh and one browser_<tool> command per tool into ~/.local/bin.
Plain REST:
URL="$(jq -r .url ~/.claude/claude-has-hands/bridge.json)"
TOKEN="$(cat ~/.claude/claude-has-hands/bridge.token)"
curl -sS -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
-d '{"tool":"browser_status","input":{}}' "${URL}/v1/call"To serve MCP over HTTP, set CHH_MCP_HTTP_PORT (or CHH_MCP_TRANSPORT=http|both) when starting mcp-adapter.js. Clients must send the same bearer token as for REST.
Tools
The tool reference is generated from the registry: see docs/tools.md. It covers navigation and tabs, accessibility-tree and DOM inspection, click, type, select, scroll and key presses, screenshots and frame-sequence capture, console and network inspection, waits, file upload, JavaScript evaluation and batches. chh tools returns the full JSON Schema for each tool.
browser_console and browser_network read ring buffers filled by a capture script injected at document_start. Network capture stores method, URL, status and timing only, never request or response bodies. Pages opened before the extension started need a reload for full coverage.
Security model
Details and reporting instructions are in SECURITY.md. In short:
The REST server binds to
127.0.0.1only.Every request needs
Authorization: Bearer <token>. The token is compared withcrypto.timingSafeEqualafter a length check.Requests carrying a browser
Originother thanlocalhost,127.0.0.1or[::1]get a 403, which blocks DNS-rebinding and cross-site requests from web pages. There is no CORS.The token is regenerated every time the host starts.
bridge.token,bridge.jsonandbridge.sockare mode 0600.The Unix socket requires a token handshake. The HTTP MCP transport applies the same origin and bearer checks as REST.
Request bodies are capped at about 1 MB, matching Chrome's native messaging frame limit. Responses carry
Cache-Control: no-store.browser_navigateaccepts only an allowlist of URL schemes.
The bridge does not read, store or replay passwords and does not bypass MFA. It can still see whatever the page shows: DOM reads, screenshots, console output and browser_eval results can contain sensitive data from a signed-in session.
Configuration
Variable | Purpose |
| Override the REST URL (default: read from |
| Override the token path |
| Override the discovery file path |
| Pin the REST port (default: OS-assigned) |
| Disable the REST server; the host serves the Unix socket only |
| Serve MCP over HTTP on this port |
|
|
Reliability
Chrome starts the native host from the extension's MV3 service worker, and the host lives only as long as that worker. The worker pings the host over the native port about every 20 seconds, which resets Chrome's idle timer, and a chrome.alarms handler restarts the connection if the worker dies anyway. Each restart means a new port and a new token, which the adapter and chh pick up from bridge.json.
Limitations and non-goals
Chrome only, on macOS and Linux. Chrome for Testing and other browsers are untested.
Single user, single machine. There is no remote access, multi-user mode or cloud browser fallback.
The extension asks for
<all_urls>and thedebuggerpermission, and Chrome shows its debugging banner while attached. Connect only agents you trust with the whole browser session.There is no per-site policy or action tiering. The calling agent or harness owns approval for actions such as submitting forms.
browser_gifreturns a frame sequence, not an encoded GIF, because one native messaging message is capped near 1 MB.No streaming events for
browser_observe.
Development
npm run typecheck
npm test # typecheck, then node --test test/unit/*.test.ts
npm run build # typecheck, then esbuild into extension/dist and native-host/dist
npm run docs:tools # regenerate docs/tools.md
npm run dev # rebuild on changeUnit tests cover the wire protocol, dispatcher, REST and MCP transports, keepalive and the tool registry, and run without a browser. The declarative scenarios in test/scenarios/ and the fixture pages in test/ are for driving a real Chrome by hand and are not part of npm test.
Licence
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Let AI agents observe and control Chrome tabs you explicitly share via Browse Bridge.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to control and inspect a live Chrome browser via MCP, providing Chrome DevTools capabilities for automation, debugging, and performance analysis.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables remote AI agents to control a local, authenticated desktop browser over MCP through an outbound WebSocket bridge and Chrome extension, supporting tab management, navigation, page reading, clicking, typing, scrolling, screenshots, and JavaScript evaluation.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables Codex or any MCP client to inspect and operate explicitly allowed browser tabs in paired Chromium profiles through a secure local-only bridge. Supports DOM snapshots with stable references, navigation, clicking, typing, scrolling, screenshots, and multiple sessions/profiles.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to interact with live Chrome and Chrome Dev sessions through MCP tools, including finding and focusing active tabs, evaluating JavaScript in tab DOMs or extension service workers, and capturing screenshots without remote-debugging consent modals.1MIT