Claude Chrome MCP
Browser automation tool enabling MCP clients (Claude Desktop, Claude Code, Cursor) to interact with claude.ai through Chrome extension and MCP server.
Components
- MCP Server
- Chrome Extension (enabled only for claude.ai)
- CLI Tool
Quick Start
Prerequisites
- Google Chrome browser
- Node.js v16 or higher
- npm installed
Step 1: Install Chrome Extension
- Open Chrome and navigate to chrome://extensions/
- Enable "Developer mode" (toggle in top right)
- Click "Load unpacked" and select the
extension/directory from this project - The extension icon should appear in your toolbar
Step 2: Install Dependencies
# From the project root directory
cd mcp-server
npm install
Step 3: Configure Claude Desktop
- Open Claude Desktop settings
- Navigate to Developer > Edit Config
- Add this configuration:
{
"mcpServers": {
"claude-chrome-mcp": {
"command": "node",
"args": ["<absolute-path-to-project>/mcp-server/src/server.js"]
}
}
}
Replace <absolute-path-to-project> with the full path to this project (e.g., /Users/yourname/claude-chrome-mcp)
Step 4: Restart Claude Desktop
After adding the configuration, restart Claude Desktop to load the MCP server. The server will automatically start its embedded WebSocket relay on port 54321.
Step 5: Test the Connection
In Claude Desktop, you can now use natural language commands like:
- "Check Chrome status"
- "Open a new tab"
- "Send 'Hello, World!' to the new Claude tab"
- "List all open Claude tabs"
- "Search for Claude chats with 'math'"
Key Features
- Async message sending with completion detection
- Claude-to-Claude response forwarding
- Conversation management via Claude.ai API
- Network inspection and debugging tools
- WebSocket-only architecture with persistent connections
- Health monitoring endpoint for relay status
Documentation
| Guide | Description |
|---|---|
| Architecture Analysis | Critical issues and improvement roadmap |
| Architecture | System design and components |
| Troubleshooting | Complete troubleshooting and timeout resolution |
| Development Workflows | Code changes, testing, and development procedures |
| TypeScript | Type definitions and development |
| CLI Tools | Command-line interface and setup |
| Event Architecture | Visual system diagrams |
Project Resources
- MCP Configuration - Quick commands and setup
- GitHub Releases - Release history
- GitHub Issue Script - Claude Code integration utilities
CLI Tool (Optional)
npm install && npm run build && npm link
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Claude.ai │ │ Chrome Extension │ │ WebSocket Relay │
│ (Browser) │◄──►┤ (Offscreen Doc) │◄──►│ Port 54321 │
└─────────────────┘ └──────────────────┘ └─────────────────┘
▲
│
┌────────┴────────┐
│ │
┌───────▼──────┐ ┌───────▼──────┐
│ MCP Server │ │ Claude Code │
│ (Relay Mode) │ │ MCP Client │
└──────────────┘ └──────────────┘