crx-mcp

MCP server for Chrome extension testing. Access chrome.storage, Service Workers, declarativeNetRequest, and more directly from AI coding agents like Claude Code.

Why?

Existing browser MCP servers (like Playwright MCP) can't access Chrome extension internals. crx-mcp fills this gap with 15 purpose-built tools for extension development and testing.

Quick Start

With Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "crx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "crx-mcp"]
    }
  }
}

Then in Claude Code:

> Load my extension from ./my-extension and check if storage is working

Claude will use extension_load, then storage_get to inspect chrome.storage

CLI

npx crx-mcp --extension-path ./my-extension --verbose

Tools (15)

Core

Tool	Description
extension_load	Load an unpacked extension and launch Chrome. Returns extension ID.
navigate	Navigate to a URL. Returns title and status code.
snapshot	Accessibility tree snapshot of page, popup, or side panel.
storage_get	Read from chrome.storage (local/sync/session).
storage_set	Write to chrome.storage (local/sync/session).
eval_service_worker	Execute JavaScript in the Service Worker context.
console_logs	Get console logs from all contexts (page, SW, popup, sidepanel).

Extension-Specific

Tool	Description
manifest_validate	Validate manifest.json against MV3 requirements (no browser needed).
open_popup	Open the extension popup and return accessibility snapshot.
open_sidepanel	Open the side panel and return accessibility snapshot.
dnr_rules	List declarativeNetRequest rules (dynamic/session/static).
permissions_check	Compare declared vs granted permissions.

Advanced

Tool	Description
screenshot	Take a PNG screenshot (base64).
network_requests	List captured network requests with URL filter.
content_script_eval	Execute JS in page context (ISOLATED or MAIN world).
reload_extension	Hot-reload the extension and re-attach to Service Worker.

CLI Options

crx-mcp [options]
  --extension-path <path>   Pre-load extension at startup
  --chrome-path <path>      Path to Chrome executable
  --user-data-dir <path>    Chrome user data directory
  --no-sandbox              Disable sandbox (for CI/Docker)
  --verbose                 Debug logging to stderr

Requirements

• Node.js >= 18
• Google Chrome installed (detected automatically on Windows, macOS, Linux)
• Extensions require headed mode (no headless)

How It Works

1. extension_load launches Chrome with --load-extension and detects the extension ID
2. Service Worker communication uses Chrome DevTools Protocol (CDP) sessions
3. chrome.storage, declarativeNetRequest, and permissions are accessed via JS evaluation in the SW context
4. Console logs are collected from all contexts (page, SW, popup, sidepanel) into a ring buffer
5. Network requests are monitored via CDP Network.enable
6. Popup and side panel are opened in new tabs (actual popup/sidepanel UI requires user gestures)

Use Cases

• Automated testing of Chrome extensions during development
• AI-assisted debugging — let Claude inspect storage, logs, and network traffic
• CI/CD validation — validate manifests and permissions without manual testing
• Extension factory workflows — quickly test multiple extensions in sequence

License

MIT