chrome-profile-debug
Drives named Google Chrome profiles through an extension and native messaging host. Provides tools to list profiles and tabs, manage tab lifecycle, navigate, read page accessibility trees and text, take screenshots, evaluate JavaScript, perform input actions, and inspect console messages and network requests within a specific Chrome profile.
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.
chrome-profile-debug
Drive any of your named Chrome profiles from an MCP client — Claude Code, Codex, or anything else that speaks MCP over stdio.
Chrome keeps every profile in one browser process. Tools that attach over
--remote-debugging-port therefore see all of your open profiles at once and
cannot tell them apart, while extension-based tools usually bind to whichever
single profile happens to be paired. Neither lets you say "work in the profile I
call staging".
This does. You name each profile once, and every tool call takes that name.
list_profiles() → ["personal", "staging", "prod-readonly"]
new_tab(profile: "staging", url: "https://app.example.com") → { tabId: 42 }
read_page(profile: "staging", tabId: 42)No listening TCP port. No telemetry. No Chrome Web Store account required.
How it works
MCP client
│ stdio
▼
server/index.js ──── Unix domain socket (0600)
▲
│ NDJSON
host/host.js ─────── one process per profile, spawned by Chrome
▲
│ Chrome native messaging
extension/ ───────── one instance per profile
│ chrome.debugger (chrome.scripting only where the debugger is refused)
▼
web pageThe wire format is specified in docs/PROTOCOL.md. The threat model and its limits are in docs/SECURITY.md.
Related MCP server: WebOperator MCP Server
Install
Requires Node.js 20+ and a Chromium-family browser.
1. Get the code
git clone https://github.com/marcondesmacaneiro/chrome-profile-debug.git
cd chrome-profile-debug
npm installKeep the directory where it is. The native messaging manifest written in step 3
points at an absolute path inside it (host/run-host.sh), so moving the folder
breaks the link until you re-run the installer.
2. Load the extension into each profile you want to drive
In each Chrome profile, separately:
Open
chrome://extensionsTurn on Developer mode
Click Load unpacked and select the
extension/directory
The extension always gets the same ID, whether it was loaded from source or installed from the Chrome Web Store:
clkflehjfcefahjgchgcomflocccphnjThat is because extension/manifest.json pins the public key. Without it, an
unpacked extension's ID derives from its absolute path and would differ on
every machine.
3. Register the native messaging host
Once per machine:
npm run install-host -- --extension-id clkflehjfcefahjgchgcomflocccphnjThis writes a manifest into Chrome's NativeMessagingHosts directory. It
contains an absolute path, so it is generated locally and never committed.
The same command covers every profile on the machine: the ID identifies the extension, not the profile.
A profile named before this step shows Not connected: Specified native messaging host not found. in its popup. It retries on its own within 30
seconds; click Save in the popup to reconnect right away.
4. Name each profile
Click the extension icon in a profile and give it a name — staging,
personal, whatever you will type in your prompts. A profile with no name
never connects, which is what makes participation opt-in.
5. Point your MCP client at the server
Claude Code:
claude mcp add --scope user chrome-profile-debug -- node /absolute/path/to/chrome-profile-debug/server/index.js--scope user makes the tools available in every directory. Without it, Claude
Code registers the server only for the directory you ran the command in.
The server only sees profiles on the machine it runs on: run your MCP client on the same computer as the browser.
Any other client: run server/index.js over stdio.
Tools
list_profiles first — everything else takes a profile name.
Tool | Purpose |
| Connected, named profiles |
| Tabs in that profile |
| Tab lifecycle |
| Open a URL |
| Accessibility tree with click-ready coordinates |
| Plain text of the page |
| PNG or JPEG of the viewport |
| Run JavaScript in the page |
| Input |
| Console messages, optionally filtered by regex |
| Network requests |
Troubleshooting
A profile does not appear in list_profiles. Check, in order: the extension
is loaded in that profile; it has a name in the popup; the native host manifest
lists that profile's extension ID; the MCP server is running.
The popup reads Not connected: .... The text after the colon is Chrome's
own reason:
Specified native messaging host not found.— step 3 has not run on this machine, or it wrote to another browser's directory.Access to the specified native messaging host is forbidden.— the host manifest does not list this extension's ID. Re-run step 3 with--extension-id clkflehjfcefahjgchgcomflocccphnj.Native host has exited.— the host started and died. Runhost/run-host.shby hand to see the error.
On Linux, the installer covers Google Chrome's .deb package. A Chromium
snap or a Flatpak browser is sandboxed and cannot launch a host
installed this way.
DEBUGGER_BUSY. Chrome allows one debugger client per tab. Close DevTools
on that tab.
RESTRICTED_URL. Extensions cannot touch chrome://, devtools://, or the
Chrome Web Store. This is a browser restriction with no workaround.
License
MIT
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
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects local stdio MCP servers to an existing Chrome 144+ session, preserving the user's signed-in sessions, cookies, tabs, and extension environment without launching a second browser. It provides tab control, semantic snapshots, screenshots, pointer, keyboard, form selection, scrolling, navigation, and waiting tools.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to drive a live Chrome or Brave browser over stdio, with tools for navigation, clicking, typing, screenshots, and executing automation goals.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to directly operate your existing logged-in Chrome profiles, including cookies and extensions, without re-authentication or a headless browser. It provides tools for managing tabs, navigating, reading pages, clicking, typing, and launching profiles.MIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools to control real, logged-in Chrome or Brave browser profiles—tabs, navigation, clicks, and typing—with secure profile isolation and no network listener.1MIT