https://github.com/syedazharmbnr1/chrome-mcp-server
Chrome Browser MCP Server — 18 tools for browser automation via Model Context Protocol. Screenshots, DOM access, JS eval, network monitoring, form filling, GIF recording. Works with Claude Code, Cursor, LM Studio, Ollama, llama.cpp, any MCP client.
https://github.com/syedazharmbnr1/chrome-mcp-server
ai-tools browser-automation chrome-extension claude-code claude-in-chrome cursor lm-studio mcp mcp-server model-context-protocol
Last synced: about 2 months ago
JSON representation
Chrome Browser MCP Server — 18 tools for browser automation via Model Context Protocol. Screenshots, DOM access, JS eval, network monitoring, form filling, GIF recording. Works with Claude Code, Cursor, LM Studio, Ollama, llama.cpp, any MCP client.
- Host: GitHub
- URL: https://github.com/syedazharmbnr1/chrome-mcp-server
- Owner: syedazharmbnr1
- Created: 2026-04-12T10:29:55.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T13:58:16.000Z (2 months ago)
- Last Synced: 2026-04-12T15:11:28.544Z (2 months ago)
- Topics: ai-tools, browser-automation, chrome-extension, claude-code, claude-in-chrome, cursor, lm-studio, mcp, mcp-server, model-context-protocol
- Language: JavaScript
- Size: 152 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Chrome MCP Server
A production-grade **Chrome Browser MCP Server** that gives any AI agent full browser automation through the [Model Context Protocol](https://modelcontextprotocol.io). Control Chrome with 18 tools — screenshots, DOM access, JavaScript execution, form filling, network monitoring, GIF recording, and more.
Works with **Claude Code**, **Cursor**, **VS Code**, **Windsurf**, **LM Studio**, **Ollama**, **llama.cpp**, **MLX**, and any MCP-compatible client.
**No domain blocklist. Any Chromium browser.** (Chrome, Brave, Edge, Arc, Opera, Vivaldi)
---
## Architecture
```
AI Client ←─ stdio MCP ─→ mcp-server.js ←─ TCP :18765 ─→ native-host.js ←─ native messaging ─→ Chrome Extension ←→ Browser
```
Three-tier bridge:
1. **Chrome Extension** (Manifest V3) — Injects into pages, provides DOM access via Chrome DevTools Protocol
2. **Native Host** (Node.js) — Bridges Chrome native messaging to TCP
3. **MCP Server** (Node.js) — Exposes 18 tools via MCP stdio transport
Multiple AI sessions can share the same browser. First session is primary (owns the TCP port), subsequent sessions connect as clients through it.
---
## 18 Tools
### Tab Management
| Tool | Description |
|------|-------------|
| `tabs_context_mcp` | Get/create MCP tab group, list available tabs with IDs |
| `tabs_create_mcp` | Create a new blank tab in the MCP group |
### Navigation
| Tool | Description |
|------|-------------|
| `navigate` | Navigate to URL, go back/forward in history |
### Interaction
| Tool | Description |
|------|-------------|
| `computer` | 13 actions: screenshot, left_click, right_click, double_click, triple_click, type, key, scroll, scroll_to, hover, zoom, left_click_drag, wait |
| `find` | Find elements by natural language query (returns refs) |
| `form_input` | Set form values (text, checkbox, select, radio) by element ref |
### Page Analysis
| Tool | Description |
|------|-------------|
| `read_page` | Full accessibility tree with element refs and interactive filter |
| `get_page_text` | Extract article/main content text from page |
| `javascript_tool` | Execute JavaScript in page context with await support |
| `read_console_messages` | Read console output with pattern/level filtering |
| `read_network_requests` | Monitor network requests with URL pattern filtering |
### Window & Media
| Tool | Description |
|------|-------------|
| `resize_window` | Resize browser window dimensions |
| `upload_image` | Upload images to file inputs or drag-drop targets |
| `gif_creator` | Record browser actions as frame sequences |
### Shortcuts & Workflows
| Tool | Description |
|------|-------------|
| `shortcuts_list` | List saved workflow shortcuts |
| `shortcuts_execute` | Execute a saved shortcut (replays tool sequences) |
### Browser Control
| Tool | Description |
|------|-------------|
| `switch_browser` | Detect current browser, guide switching to another Chromium browser |
| `update_plan` | Present action plan to user |
---
## Quick Start
```bash
# 1. Clone
git clone https://github.com/syedazharmbnr1/chrome-mcp-server.git
cd chrome-mcp-server
# 2. Install dependencies
cd host && npm install && cd ..
# 3. Load extension in Chrome
# chrome://extensions → Developer Mode ON → Load Unpacked → select extension/ folder
# Copy the Extension ID shown
# 4. Register native messaging host
./install.sh
# 5. Restart Chrome (close all windows, reopen)
# 6. Add to Claude Code
claude mcp add chrome-mcp-server -- node /path/to/chrome-mcp-server/host/mcp-server.js
```
---
## Installation
### Prerequisites
- **Node.js 18+**
- **Chrome, Brave, Edge, Arc, Opera, or Vivaldi**
- **macOS or Linux** (Windows: manual registry setup)
### Step 1: Install Dependencies
```bash
git clone https://github.com/syedazharmbnr1/chrome-mcp-server.git
cd chrome-mcp-server/host
npm install
```
### Step 2: Load the Chrome Extension
1. Open `chrome://extensions` in your browser
2. Enable **Developer mode** (top right toggle)
3. Click **Load unpacked**
4. Select the `extension/` folder from this project
5. Copy the **Extension ID** shown on the card
### Step 3: Register Native Messaging Host
```bash
cd chrome-mcp-server
./install.sh
```
This registers the native host for Chrome, Edge, and Brave automatically.
### Step 4: Restart Browser
Close ALL browser windows and reopen. The native messaging host only loads on browser startup.
### Step 5: Verify
Open any webpage in the browser. The extension icon should be visible.
---
## Configuration for AI Clients
### Claude Code
```bash
claude mcp add chrome-mcp-server -- node /absolute/path/to/host/mcp-server.js
```
Or add to `~/.claude.json`:
```json
{
"mcpServers": {
"chrome-mcp-server": {
"type": "stdio",
"command": "node",
"args": ["/path/to/chrome-mcp-server/host/mcp-server.js"],
"env": {}
}
}
}
```
### Cursor
Create `.cursor/mcp.json`:
```json
{
"mcpServers": {
"chrome-mcp-server": {
"command": "node",
"args": ["/path/to/chrome-mcp-server/host/mcp-server.js"]
}
}
}
```
### VS Code + GitHub Copilot
Create `.vscode/mcp.json`:
```json
{
"mcpServers": {
"chrome-mcp-server": {
"command": "node",
"args": ["/path/to/chrome-mcp-server/host/mcp-server.js"]
}
}
}
```
### Windsurf
Edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"chrome-mcp-server": {
"command": "node",
"args": ["/path/to/chrome-mcp-server/host/mcp-server.js"]
}
}
}
```
### LM Studio / Ollama / llama.cpp / MLX
Use [MCP-Bridge](https://github.com/SecretiveShell/MCP-Bridge) to connect local models to this MCP server:
```json
{
"inference_server": {
"base_url": "http://localhost:11434/v1"
},
"mcp_servers": {
"chrome-mcp-server": {
"command": "node",
"args": ["/path/to/chrome-mcp-server/host/mcp-server.js"]
}
}
}
```
**Recommended models for tool calling (April 2026):** Gemma 4 31B, Qwen 3.5/3.6, Llama 4 Scout, GLM-5.1, Kimi K2.5, Mistral Small 4.
---
## How It Works
### Communication Flow
```
User asks AI to "click the login button"
↓ MCP tool call (stdio)
mcp-server.js → sends {tool: "computer", args: {action: "left_click", coordinate: [200, 300]}}
↓ TCP (localhost:18765)
native-host.js → converts to native messaging format (4-byte LE length + JSON)
↓ Chrome native messaging
Extension background.js → dispatches to toolHandler
↓ Chrome DevTools Protocol
Browser executes Input.dispatchMouseEvent at (200, 300)
↓ Response flows back through the same chain
AI receives confirmation
```
### Key Implementation Details
- **Element References**: Persistent refs (`ref_1`, `ref_2`) using WeakRef for GC-safe DOM element tracking
- **CDP Integration**: Chrome DevTools Protocol for screenshots, input simulation, JS evaluation, network capture
- **Retina Handling**: Device pixel ratio forced to 1:1 so screenshot coordinates match CSS coordinates
- **Multi-Session**: First MCP server instance owns the TCP port (primary), subsequent ones connect as clients
- **Keep-Alive**: Extension service worker stays alive via Chrome alarms (every 24 seconds)
---
## Troubleshooting
### Extension not connecting
- Ensure Developer Mode is ON in `chrome://extensions`
- Check the service worker is running (click "Inspect views: service worker")
- Restart browser after running `install.sh`
### "Browser extension is not connected"
- Open any webpage first (extension needs an active tab)
- Check native messaging manifest exists: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.open_claude_in_chrome.json`
### Port conflict
Create `~/.config/open-claude-in-chrome/config.json`:
```json
{"port": 19000}
```
### Multiple sessions
First Claude Code session = primary. Kill it with `kill $(cat /tmp/open-claude-in-chrome-mcp-18765.pid)` to release the port.
---
## Project Structure
```
chrome-mcp-server/
├── extension/
│ ├── manifest.json # Manifest V3 config (permissions, content scripts)
│ ├── background.js # Service worker: 18 tool handlers, CDP, native messaging
│ └── content.js # DOM injection: accessibility tree, element refs, form filling
├── host/
│ ├── mcp-server.js # MCP stdio server with tool schemas (primary/client mode)
│ ├── native-host.js # Native messaging ↔ TCP bridge
│ └── package.json # Dependencies (@modelcontextprotocol/sdk)
├── install.sh # Native host registration for Chrome/Edge/Brave
├── vitest.config.js # Test configuration
├── tests/
│ ├── mocks/chrome.js # Chrome API mock infrastructure
│ ├── content.test.js # Content script tests (19 tests)
│ ├── background.test.js # Background service worker tests (38 tests)
│ ├── native-host.test.js# Native messaging protocol tests (10 tests)
│ └── mcp-server.test.js # MCP server infrastructure tests (22 tests)
└── README.md
```
---
## Testing
### Automated Tests (89 tests)
```bash
cd chrome-mcp-server && npx vitest run
```
| Test File | Tests | Coverage |
|-----------|:-----:|----------|
| `content.test.js` | 19 | Element refs, find (tokenized word matching), page text, form input, accessibility tree, coordinates |
| `background.test.js` | 38 | All 18 tool handlers, CDP domains, tab groups, screenshots, native messaging, GIF recording, shortcuts, upload |
| `native-host.test.js` | 10 | 4-byte LE native messaging protocol, read/write/roundtrip, partial messages, unicode, malformed JSON |
| `mcp-server.test.js` | 22 | Port config, response routing, arg coercion, result helpers, schema validation (18 tools, 13 computer actions) |
### Live Integration Tests (28 tests)
Tested across 3 simultaneous tabs on complex dynamic sites:
| Category | Tests | Sites |
|----------|:-----:|-------|
| Tab management | 3 | Multi-tab create, group, context |
| Navigation | 2 | Navigate + browser history back |
| Form filling | 5 | Text, email, number, password, textarea (demoqa.com, expandtesting.com, herokuapp.com) |
| Click actions | 3 | left_click, double_click, right_click with dynamic DOM verification (demoqa.com/buttons) |
| Computer actions | 4 | screenshot, scroll_to, key (cmd+a), wait, zoom |
| Page analysis | 4 | read_page, find, get_page_text, javascript_tool |
| Monitoring | 2 | read_console_messages (18 entries captured), read_network_requests |
| Media/Window | 3 | GIF start/stop/export, resize_window |
| Login flow | 1 | Full login on herokuapp.com — credentials filled, submitted, verified "Secure Area" |
| Other | 1 | shortcuts_list, switch_browser, update_plan |
**Result: 28/28 live tests passed. Login flow verified end-to-end.**
---
## Contributing
1. Add new tools in `extension/background.js` under `toolHandlers`
2. Define the tool schema in `host/mcp-server.js`
3. Run tests: `npx vitest run`
4. Test live with Claude Code: `claude mcp add chrome-mcp-server -- node host/mcp-server.js`
---
## License
MIT License — see [LICENSE](LICENSE) for details.
Based on [open-claude-in-chrome](https://github.com/noemica-io/open-claude-in-chrome) by noemica.io.