Chrome Profile 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: --profile is 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

1. Reads Chrome's Local State to discover available profiles
2. Launches Chrome with --remote-debugging-port using the selected profile
3. Connects via Chrome DevTools Protocol (CDP) using Playwright
4. Starts an MCP server on stdio that exposes 20 browser control tools
5. 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-port on the same port
• CDP has lower fidelity than Playwright's native protocol for some operations
• get_page_content truncates 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