# cdp-toolkit [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/sblattj/cdp-toolkit  
**GitHub Stars:** 1  
**npm Downloads (last month):** 2796  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cdp-toolkit

## Description
A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome o

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "cdp-toolkit": {
    "command": "npx",
    "args": ["-y","--package","cdp-toolkit","cdp"]
  }
}
```

## Documentation

## What cdp-toolkit does

cdp-toolkit gives MCP-compatible agents and a command-line client direct control of browser tabs that the user identifies. Targets can be selected as the active tab, an index, a URL, or a title. Chrome is the primary backend, while Firefox is supported through WebDriver BiDi behind the same tool interface.

The server is designed for tasks where the agent already knows which page to operate. It does not manage a Puppeteer browser or broadcast every operation to all attached targets. Multiple tabs can still be driven across separate calls, and tab leases help multiple agents share one browser without taking control of each other’s tabs. The lease state also indicates when a human is using a tab.

A built-in fake backend can persist mocked network responses for a target, which is useful for exercising a UI before its real API is available.

## How it works

Each operation resolves one named target and creates a direct WebSocket connection for that call. The connection is closed when the call finishes, preventing state from leaking between tabs. CDP domains are enabled only when a tool needs them rather than eagerly at connection time.

Every command has a bounded timeout. The default is 15 seconds, configurable with `CDP_TIMEOUT_MS`. If a renderer or endpoint stops responding, the operation returns an error instead of leaving the agent or MCP process waiting indefinitely. The affected page may remain unresponsive until it is closed, but other tabs and the server can continue operating.

The MCP listing uses progressive disclosure: seven static entries expose five common tools plus `search_tools` and `call_tool`. The latter two locate and invoke the broader tool set. Setting `CDP_TOOL_PROFILE=full` exposes all 48 tools in the listing instead.

## Setup and configuration

The package requires Node.js 22 or newer, or Bun 1.1 or newer. The interactive installer can register the server with Claude Code, Codex, or OpenCode, configure a browser and debugging port, and optionally add a shell alias. It supports Chrome, Arc, Firefox, and Vivaldi as installer browser choices.

For a manual Chrome setup, start the browser with remote debugging enabled, then register the stdio server with an MCP host. For example:

```bash
claude mcp add cdp-toolkit --scope user -- npx -y cdp-toolkit
```

The package can also be invoked directly through its CLI:

```bash
npx -y --package cdp-toolkit cdp list_pages
npx -y --package cdp-toolkit cdp navigate_page --target index:0 --url https://example.com
```

Chrome is connected lazily when a call is made, so the server can start before the browser is running. Firefox’s generated launcher includes the Marionette option needed for orphaned-session recovery.

## Tools and capabilities

- List available pages and resolve targets by activity, index, URL, or title.
- Navigate pages, click elements, enter text, inspect page content, and evaluate scripts.
- Capture screenshots for visual checks and evidence gathering.
- Mock network responses with a persistent fake backend scoped to a target.
- Coordinate shared browser access with tab leases.
- Discover and call the extended tool set through `search_tools` and `call_tool`.
- Run the same tool surface from MCP hosts or the standalone CLI.

## Limitations and notes

Operations are single-shot rather than wrapped in Puppeteer-style auto-wait and retry behavior. Callers should re-snapshot between steps when page state changes. The design is intended for explicitly selected tabs, not autonomous fan-out across every open target.

Safari and WebKit are not supported. A page stuck during navigation can remain blocked until that tab is closed and reopened, although the MCP server and other tabs remain available. The server uses stateless `backendDOMNodeId` element references that are resolved when needed rather than retaining a server-side handle table.

_Full upstream README: https://allmcps.com/mcp/cdp-toolkit/readme_