Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-chromium-cdp navigate to example.com and get the page title"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for controlling Chromium/Chrome via Chrome DevTools Protocol. Cross-platform with automatic reconnection support.
✅ 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
Related MCP server: ChromeCP
npm install -g mcp-chromium-cdpnpm install mcp-chromium-cdpgit clone https://github.com/duquesnay/mcp-chromium-cdp.git
cd mcp-chromium-cdp
npm install
npm run buildAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"chromium": {
"command": "npx",
"args": ["-y", "mcp-chromium-cdp"]
}
}
}claude mcp add chromium -- npx -y mcp-chromium-cdpOr with local build:
claude mcp add chromium -- node /path/to/mcp-chromium-cdp/build/index.jsCHROMIUM_PATHOverride Chromium binary path:
CHROMIUM_PATH=/usr/bin/chromium-browser mcp-chromium-cdpCHROMIUM_USER_DATA_DIRUse custom browser profile:
CHROMIUM_USER_DATA_DIR=~/.config/chromium-mcp mcp-chromium-cdpTool | Description |
| Navigate to a specific URL |
| Get the current page URL |
| Get the page title |
| Get the page HTML content |
| Get visible text from the page |
| Execute JavaScript in the page |
| Click an element by CSS selector |
| Type text into an input field |
| Take a screenshot (base64) |
| Open a new tab |
| Close the current tab |
| List all open tabs |
| Reload the current page |
| Navigate back in history |
| Navigate forward in history |
Using chromium tools, navigate to https://example.com and get the page titleimport { 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);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 ChromiumThe 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.
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run watchThis project consists of two main components:
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
MCP Server (src/index.ts):
Implements the Model Context Protocol server
Exposes Chrome control methods as MCP tools
Handles communication via stdio
If the server can't find Chromium:
Install Chromium from chromium.org
Or specify path manually:
CHROMIUM_PATH=/path/to/chromium mcp-chromium-cdpIf the server can't connect:
Check if another process is using port 9222:
lsof -i :9222The server will auto-launch Chromium if not running
Check logs for reconnection attempts
Verify configuration in Claude Desktop/Code
Check that build/index.js exists
Look at Claude logs for errors
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
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
MIT
Contributions welcome! Please open an issue or PR on GitHub.
Issues: GitHub Issues
Discussions: GitHub Discussions
Quick page state check without screenshot (fast health-check for autonomous agents). Returns URL, title, load state, visible errors, form count, and interactive elements count. Response time < 500ms.
Inputs: no named parameters.
Click on an element using a CSS selector. For React SPAs, use ensureInteractive option to trigger synthetic event handlers.
Inputs: selector (required), ensureInteractive.
Click an element by its visible text content (semantic alternative to chrome_click). Uses XPath contains() for text matching. Optionally filter by ARIA role. Returns actionable error with suggestions if 0 or >1 matches found. Prefer this over chrome_execute_script for clicking buttons/links.
Inputs: text (required), role.
Close the current tab
Inputs: no named parameters.
Detect SPA frameworks on the page (React, Vue, Angular, Svelte). Returns framework names and versions. Use this to determine if ensureInteractive pattern is needed for clicks.
Inputs: no named parameters.
Execute JavaScript in the current page and return the result. ADVANCED: Use as last resort when chrome_click, chrome_type, or other structured tools cannot accomplish the task. Prefer semantic tools for better reliability.
Inputs: script (required).
Extract structured form data without custom scripting. Returns fields (name, type, value, placeholder, required, label, validation rules), submit buttons, and fieldsets. Works with standard forms, React forms, and Shadow DOM forms. Identifies filled vs empty fields.
Inputs: formSelector.
Extract all interactive elements with their text and metadata. Returns buttons, links, inputs with text, role, selector, visibility, and enabled status. Limited to 100 elements for performance. Use this to discover available interactions before calling chrome_click_text or chrome_type_text.
Inputs: no named parameters.
Get the HTML content of the current page
Inputs: no named parameters.
Get the current URL of the active tab
Inputs: no named parameters.
Get a property value from an element without script injection. Uses CDP APIs for safe property access. Property name must be alphanumeric + underscore/hyphen only. Use this instead of chrome_execute_script for reading element properties.
Inputs: property (required), selector (required).
Get the title of the current page
Inputs: no named parameters.
Get the visible text content of the current page
Inputs: no named parameters.
Go back in browser history
Inputs: no named parameters.
Go forward in browser history
Inputs: no named parameters.
Hover over an element using a CSS selector. Essential for React SPAs where hover activates synthetic event handlers. Use before chrome_click when dealing with dropdowns, tooltips, or interactive elements that require hover state.
Inputs: selector (required).
List all open tabs with their titles and URLs
Inputs: no named parameters.
Open a new tab in Chrome, optionally with a URL
Inputs: url.
Reload the current page
Inputs: no named parameters.
Take a screenshot of the current page with automatic resizing to fit API limits (returns base64 encoded PNG with metadata)
Inputs: maxDimension.
Scroll the page or a specific element. Supports direction (up/down/top/bottom), distance (pixels), element targeting (selector), and behavior (instant/smooth). Returns scroll position, boundary detection (atTop/atBottom), and dimensions. Useful for infinite scroll detection and pagination.
Inputs: direction (required), behavior, distance, selector.
Type text into an input field using a CSS selector
Inputs: text (required), selector (required).
Type text into an input field by its associated label (semantic alternative to chrome_type). Searches for input by: label "for" attribute, parent label, aria-label, placeholder (in order). Returns actionable error with suggestions if input not found or multiple matches. Prefer this over chrome_execute_script for form filling.
Inputs: text (required), label (required).
Wait for UI state changes after actions. Returns success status, which conditions were met, actual state, and time elapsed. On timeout, returns current state (not error) so agent can decide next action. Can chain multiple conditions.
Inputs: url, text, element, timeout, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 25 tools
Each tool has a clearly distinct purpose, with intentional separation between selector-based and semantic alternatives (e.g., chrome_click vs chrome_click_text, chrome_type vs chrome_type_text). Descriptions explicitly note when to prefer which tool, reducing ambiguity.
All tools follow a consistent chrome_ prefix with verb_noun (or verb_preposition) structure, e.g., chrome_navigate, chrome_get_title, chrome_click_text, chrome_wait_for. The naming pattern is uniform and predictable.
At 25 tools, the set is on the heavier side but each tool serves a specific browser automation need, including advanced features like SPA detection and form extraction. The count is justified for a comprehensive CDP-based server, though it could be streamlined slightly.
The toolset covers the core browser automation lifecycle: navigation, interaction, content extraction, tab management, waiting, scrolling, and state checks. Minor gaps exist (e.g., no cookie management or file upload), but the included tools enable effective automation for most scenarios.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
MCP server to assist with JxBrowser development.
Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
A remote MCP server to convert HTML documents (URL or raw source) to PDF or screenshots
