README.md
Control a real Google Chrome instance using specific user profiles
Chrome Profile MCP Server
MCP server that launches Chrome with a specific user profile and exposes browser control tools via the Model Context Protocol. AI agents (Claude Code, Claude Desktop, etc.) can then navigate, click, type, take screenshots, and more — all using your real Chrome sessions, cookies, and extensions.
Quick Start
# Interactive mode — pick a profile
npx chrome-profile-mcp
# Non-interactive — specify profile directly
npx chrome-profile-mcp --profile "Default"
CLI Flags
| Flag | Description | Default |
|---|---|---|
-p, --profile <name> |
Chrome profile directory name (skip selection) | interactive |
--port <number> |
CDP debugging port | 9222 |
--debug |
Enable debug logging | off |
Claude Code Integration
Add to .mcp.json in your project root:
{
"mcpServers": {
"chrome": {
"type": "stdio",
"command": "npx",
"args": ["-y", "chrome-profile-mcp", "--profile", "Default"]
}
}
}
Or with a local build:
{
"mcpServers": {
"chrome": {
"type": "stdio",
"command": "node",
"args": ["/path/to/chrome-profile-mcp/dist/cli.js", "--profile", "Default"]
}
}
}
Claude Desktop Integration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"chrome-browser": {
"command": "node",
"args": ["/path/to/chrome-profile-mcp/dist/cli.js", "--profile", "Default"]
}
}
}
Note:
--profileis required for Claude Code/Desktop since there's no TTY for interactive selection.
Available Tools (18)
Navigation (8)
| Tool | Description |
|---|---|
navigate |
Navigate active tab to a URL |
go_back |
Go back in browser history |
go_forward |
Go forward in browser history |
reload |
Reload current page |
list_tabs |
List all open tabs with URLs |
switch_tab |
Switch active tab by index |
new_tab |
Open new tab (optionally with URL) |
close_tab |
Close tab by index (default: active) |
Interaction (6)
| Tool | Description |
|---|---|
click |
Click element by CSS selector |
type |
Type text into input element |
scroll |
Scroll page or element into view |
hover |
Hover over element |
select_option |
Select dropdown option |
press_key |
Press keyboard key |
Inspection (4)
| Tool | Description |
|---|---|
screenshot |
Capture page/element screenshot (returns PNG) |
get_page_content |
Get page HTML or element text |
evaluate_js |
Execute JavaScript in page context |
wait_for |
Wait for element to appear |
How It Works
- Reads Chrome's
Local Stateto discover available profiles - Launches Chrome with
--remote-debugging-portusing the selected profile - Connects via Chrome DevTools Protocol (CDP) using Playwright
- Starts an MCP server on stdio that exposes 20 browser control tools
- AI agents call tools to control your real Chrome browser
Requirements
- macOS (Chrome path hardcoded to
/Applications/Google Chrome.app) - Google Chrome installed (launched at least once)
- Node.js 18+
Known Limitations
- macOS only (Linux/Windows paths not yet supported)
- Chrome must not already be running with
--remote-debugging-porton the same port - CDP has lower fidelity than Playwright's native protocol for some operations
get_page_contenttruncates at 50K chars to prevent context overflow
Development
npm install
npm run build
npm run dev # Run with tsx (interactive mode)
npm run dev -- --profile Default # Non-interactive
License
MIT
Tools (18)
navigateNavigate active tab to a URLgo_backGo back in browser historygo_forwardGo forward in browser historyreloadReload current pagelist_tabsList all open tabs with URLsswitch_tabSwitch active tab by indexnew_tabOpen new tab (optionally with URL)close_tabClose tab by index (default: active)clickClick element by CSS selectortypeType text into input elementscrollScroll page or element into viewhoverHover over elementselect_optionSelect dropdown optionpress_keyPress keyboard keyscreenshotCapture page/element screenshot (returns PNG)get_page_contentGet page HTML or element textevaluate_jsExecute JavaScript in page contextwait_forWait for element to appearConfiguration
claude_desktop_config.json
{"mcpServers": {"chrome-browser": {"command": "node", "args": ["/path/to/chrome-profile-mcp/dist/cli.js", "--profile", "Default"]}}}Try it
→Navigate to github.com and list all open tabs.
→Take a screenshot of the current page and save it.
→Type 'Hello World' into the search input on the current page and press Enter.
→Find the element with selector '#submit-button' and click it.
→Get the page content of the current tab to summarize the article.