autochrome-bridge
v1.5.0
Published
MCP server and local HTTP/WebSocket bridge that lets AI tools control Chrome through the autochrome extension.
Maintainers
Readme
autochrome-bridge
Lets outside tools control your real Chrome through the autochrome extension: Claude Code, Cursor or any MCP client over stdio, and your own scripts over HTTP or WebSocket.
Claude Code ─stdio─ autochrome-bridge ─┐
Cursor ─stdio─ autochrome-bridge ─┼─ hub (127.0.0.1:47800) ─ Chrome extension
script ─HTTP / WebSocket─────────┘One process owns the port (the hub) and holds the extension connection. Every
autochrome-bridge MCP process joins the hub, or starts it if nobody is listening. If the hub's
process exits, one of the others takes over.
Install
Requires Node 22 or newer and the autochrome extension.
Claude Code
claude mcp add autochrome -- npx -y autochrome-bridgeCursor (~/.cursor/mcp.json) and other MCP clients:
{
"mcpServers": {
"autochrome": { "command": "npx", "args": ["-y", "autochrome-bridge"] }
}
}Tools
All 21 tools are exposed over MCP and the HTTP/WebSocket API: tabs (tabs_list, tab_open,
tab_switch, tab_close, navigate, go_back, go_forward), reading (read_page, find,
get_text, screenshot), acting (click, type, key, scroll, form_input, wait) and
debugging (console_logs, network_requests, network_response, js_eval). Use GET /v1/tools
for the exact descriptions and input schemas. Tabs the agent opens go in their own tab group; pass
the tabId that tab_open returns to work across several tabs.
Approvals
Bridge calls go through the same safety checks as the side panel agent, using the mode chosen in the extension's Settings → Safety (default: per-site). A call that needs approval waits until you answer:
- If the side panel is open, the prompt appears in the chat, labelled "From an external tool". Otherwise a small popup window opens.
- Choose Allow once, Allow on this site (not offered for risky actions) or Deny. No answer within 2 minutes counts as a denial.
- A denial comes back as a normal failed result (
ok: false, "The user denied this action."), so the client can adapt instead of hanging. js_evalasks every time, in every mode. Risky clicks and form entries (purchases, sending, deleting, password and card fields) ask even on allowed sites, except in Auto mode.
Because a waiting approval keeps the call open, set a long enough timeout in your client. The HTTP API gives up on a call after 120 seconds.
Pair the extension
The first run creates a token in ~/.autochrome/token (directory 0700, file 0600).
- Run
npx autochrome-bridge tokenand copy the output. - Open the autochrome side panel in Chrome, go to Settings → Bridge, paste the token and save.
- The status dot turns green once the extension is connected.
Set AUTOCHROME_TOKEN to use a different token without touching the file.
Port
The default port is 47800. Change it with --port <n> or AUTOCHROME_PORT, and enter the same
port in the extension's Bridge settings. The hub only listens on 127.0.0.1.
Commands
| Command | What it does |
| --------------------------- | ------------------------------------------------ |
| autochrome-bridge (mcp) | MCP server on stdio; joins or starts the hub |
| autochrome-bridge serve | Standalone hub for scripts, no MCP client needed |
| autochrome-bridge token | Prints the pairing token |
HTTP API
Every request needs Authorization: Bearer <token>. Requests that carry a browser Origin
header are refused, so web pages cannot reach the hub.
TOKEN=$(npx autochrome-bridge token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:47800/v1/status
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:47800/v1/tools
curl -X POST -H "Authorization: Bearer $TOKEN" \
-d '{"url":"https://example.com"}' http://127.0.0.1:47800/v1/tools/tab_open
curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:47800/v1/tools/read_pageGET /v1/statusreturns{ "extensionConnected": boolean, "protocolVersion": number }.GET /v1/toolsreturns each tool's name, description and JSON Schema input.POST /v1/tools/:nametakes the tool input as the JSON body and returns{ "id", "ok", "content": [...] }. The status is200even whenokisfalse(for example when Chrome is not connected);4xxis only for a bad token, an unknown tool or invalid JSON. Calls time out after 120 seconds.
WebSocket API
Connect to ws://127.0.0.1:47800/client and send {"type":"hello","role":"client","token":"…",
"protocolVersion":1} first. Then send {"type":"call","call":{"id":"1","name":"tabs_list","input":{}}}
and read {"type":"result","result":{…}}. The hub also sends status messages when the extension
connects or disconnects. The message schemas live in packages/shared/src/bridge.ts.
