chrome-tab
v4.0.0
Published
Sugar for Chrome's devtools protocol
Readme
chrome-tab
Sugar for Chrome's devtools protocol.
Why
chrome-devtools-mcp crashed my machine. The issue appears to worsen with the number of tabs, and I have far too many of those. Raw CDP isn't smooth either as there is currently no straightforward way to get a page session for an active tab, also Chrome's JSON-RPC layer diverged from spec (sessionId outside params, demanding numeric message IDs, etc).
How
- Auto-discovers your running Chromium-based browser on macOS, Linux, and Windows. No flags or restarts.
- Workaround for cleanly finding active tabs / pages / sessionIds.
- stdio based MCP server with just a pinch of sugar, dumb proxy for everything else.
Usage
import Chrome from 'chrome-tab'
// Connect to Chrome's root debugging port (auto-discovers port or defaults to 9222)
const browser = new Chrome()
await browser.connect()
// List open active tabs (default)
const tabs = await browser.listTabs()
const targetId = tabs[0].targetId
// Attach to the tab to obtain its page sessionId
const sessionId = await browser.attachTab(targetId)
// Run JavaScript in that tab session
const { result } = await browser.call('Runtime.evaluate', {
expression: 'document.title',
returnByValue: true
}, sessionId)
// Navigate that tab session
await browser.call('Page.navigate', { url: 'https://github.com' }, sessionId)
// Capture screenshot
const { data } = await browser.call('Page.captureScreenshot', {}, sessionId)MCP
Config
{
"mcpServers": {
"chrome-tab": {
"command": "npx",
"args": ["-y", "chrome-tab"]
}
}
}Options
--browser,-borCHROME_BROWSER: Target a specific browser flavor (chrome, canary, chromium, edge, brave, arc, vivaldi, opera).--user-data-dirorCHROME_USER_DATA_DIR: Discover the active port from a specific user data directory (overrides --browser).--port,-porCHROME_PORT: Connect directly to an explicit port (overrides --user-data-dir and --browser).--host,-horCHROME_HOST: Host to connect to (default: 127.0.0.1).--pathorCHROME_PATH: Custom WebSocket path.
Tools
list_tabs({ query? })- Lists active tabs (one per window); passqueryto search all including background tabs.attach_tab({ targetId?, url? })- Attaches to a tab bytargetId, or passurlto open and attach. Sets it as default target.eval({ expression, wait?, sessionId? })- Evaluates JavaScript in REPL mode and returns the trailing expression value.screenshot({ format?, quality?, sessionId? })- Captures a screenshot of the tab.call({ method, params?, sessionId? })- Universal CDP passthrough for raw commands.
Security
Because chrome-tab attaches to your live browser and grants raw CDP access, it automatically inherits all of your authenticated sessions, cookies and other local storage along with full code execution privileges. Treat agent browser access like you would shell access. Hallucinations, mistakes and prompt injection are real, you've been warned!
License
MIT
