duquesnay/mcp-chromium-cdp

mcp-chromium-cdp

Model Context Protocol (MCP) server for controlling Chromium/Chrome via Chrome DevTools Protocol. Cross-platform with automatic reconnection support.

✨ Key Features

• ✅ Cross-platform: Works on macOS, Linux, and Windows
• ✅ Chromium-first: Detects and launches Chromium, falls back to Chrome
• ✅ Auto-reconnection: Automatically reconnects if browser crashes or restarts (up to 5 retries)
• ✅ Auto-launch: Launches browser automatically if not running
• ✅ Custom profiles: Support for custom browser profiles via environment variables
• ✅ Stdio transport: Native integration with Claude Desktop and Claude Code

Installation

Global Installation

npm install -g mcp-chromium-cdp

Local Installation

npm install mcp-chromium-cdp

From Source

git clone https://github.com/duquesnay/mcp-chromium-cdp.git
cd mcp-chromium-cdp
npm install
npm run build

Configuration

Claude Desktop (macOS)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "chromium": {
      "command": "npx",
      "args": ["-y", "mcp-chromium-cdp"]
    }
  }
}

Claude Code

claude mcp add chromium -- npx -y mcp-chromium-cdp

Or with local build:

claude mcp add chromium -- node /path/to/mcp-chromium-cdp/build/index.js

Environment Variables

CHROMIUM_PATH

Override Chromium binary path:

CHROMIUM_PATH=/usr/bin/chromium-browser mcp-chromium-cdp

CHROMIUM_USER_DATA_DIR

Use custom browser profile:

CHROMIUM_USER_DATA_DIR=~/.config/chromium-mcp mcp-chromium-cdp

Available Tools

Usage Examples

With Claude

Using chromium tools, navigate to https://example.com and get the page title

Programmatic Usage

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', 'mcp-chromium-cdp']
});

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Navigate to URL
await client.callTool({
  name: 'chrome_navigate',
  arguments: { url: 'https://example.com' }
});

// Get page title
const result = await client.callTool({
  name: 'chrome_get_title',
  arguments: {}
});

console.log(result.content[0].text);

Auto-Reconnection

If Chromium crashes or is restarted, the server will automatically attempt to reconnect:

• Max retries: 5 attempts
• Retry delay: 2 seconds between attempts
• Logs: Reconnection attempts logged to stderr

Example log output:

[Connection] Chromium disconnected
[Reconnect] Attempting to reconnect to Chromium...
[Reconnect] Successfully reconnected to Chromium

Chromium Detection

The server automatically detects Chromium in standard locations:

macOS:

• /Applications/Chromium.app/Contents/MacOS/Chromium
• ~/Applications/Chromium.app/Contents/MacOS/Chromium

Linux:

• /usr/bin/chromium
• /usr/bin/chromium-browser
• /snap/bin/chromium

Windows:

• %LOCALAPPDATA%\Chromium\Application\chrome.exe
• %PROGRAMFILES%\Chromium\Application\chrome.exe
• %PROGRAMFILES(X86)%\Chromium\Application\chrome.exe

If Chromium is not found, the server falls back to Chrome via chrome-launcher.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

Architecture

This project consists of two main components:

1. ChromeController (src/chrome-controller.ts):

   • Manages Chrome DevTools Protocol (CDP) connections
   • Implements browser automation methods
   • Handles auto-launch and reconnection logic
   • Cross-platform Chromium detection

2. MCP Server (src/index.ts):

   • Implements the Model Context Protocol server
   • Exposes Chrome control methods as MCP tools
   • Handles communication via stdio

Troubleshooting

Chromium/Chrome Not Found

If the server can't find Chromium:

1. Install Chromium from chromium.org
2. Or specify path manually:

   CHROMIUM_PATH=/path/to/chromium mcp-chromium-cdp
   

Connection Issues

If the server can't connect:

1. Check if another process is using port 9222:

   lsof -i :9222
   

2. The server will auto-launch Chromium if not running

3. Check logs for reconnection attempts

MCP Server Not Showing in Claude

1. Verify configuration in Claude Desktop/Code
2. Check that build/index.js exists
3. Look at Claude logs for errors

Differences from chrome-mcp

This project is based on the original chrome-mcp package by @moe03 with the following enhancements:

• ✅ Chromium-first detection (instead of Chrome-only)
• ✅ Automatic reconnection on disconnection
• ✅ Cross-platform Chromium path detection
• ✅ Environment variable configuration
• ✅ TypeScript source code included
• ✅ Improved error handling and logging

Credits

Original code by @moe03 (chrome-mcp package).

Enhanced with auto-reconnection and cross-platform support by @duquesnay.

Built using:

• @modelcontextprotocol/sdk - MCP SDK
• chrome-launcher - Chrome launcher
• chrome-remote-interface - Chrome DevTools Protocol client

License

MIT

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions