Chrome Extension Tester MCP

Give your AI assistant eyes and hands for Chrome Extension development.
Launch a real browser, load your unpacked extension, capture screenshots, click UI, and read console logs — all through the Model Context Protocol.

Quick Start · IDE Setup · Tools · For AI Agents · Contributing

Why this exists

Building Chrome Extensions with AI is painful when every change needs manual browser work:

1. Open chrome://extensions and click Reload
2. Re-open your popup or side panel
3. Click around to see if it works
4. Screenshot, paste into chat, describe the bug

This MCP server closes that loop. Your AI can build, launch, visually verify, and debug your extension without you acting as the clicker.

Features

| Capability | What it does | |------------|--------------| | Real browser | Headful Chromium with your unpacked MV2/MV3 extension loaded | | Visual verification | Screenshots saved straight into your workspace | | Interaction | Click elements via CSS selectors | | Debugging | Unified console log stream from pages and scripts | | Zero config option | Set CHROME_EXTENSION_PATH once, skip repeating paths |

Tools

| Tool | Description | |------|-------------| | launch_browser | Start Chromium with your extension; optional URL and viewport size | | take_extension_screenshot | Capture the active view to a file in your workspace | | click_element | Click by CSS selector (e.g. button#save) | | get_browser_logs | Return captured console output since launch | | close_browser | End the session cleanly |

Quick Start

Prerequisites

• Node.js 18+
• A built extension folder containing manifest.json (e.g. dist/)

Run instantly with npx

npx -y chrome-extension-tester-mcp

Or install globally

npm install -g chrome-extension-tester-mcp
chrome-extension-tester-mcp

Optional: default extension path

export CHROME_EXTENSION_PATH="/absolute/path/to/your/extension/dist"

IDE Setup

Cursor (recommended)

1. Open Cursor Settings → Features → MCP
2. Click + Add New MCP Server
3. Use:

| Field | Value | |-------|-------| | Name | chrome-extension-tester | | Type | command | | Command | npx | | Args | -y, chrome-extension-tester-mcp |

Or paste the ready-made config from examples/cursor-mcp.json.

{
  "mcpServers": {
    "chrome-extension-tester": {
      "command": "npx",
      "args": ["-y", "chrome-extension-tester-mcp"],
      "env": {
        "CHROME_EXTENSION_PATH": "/absolute/path/to/your/extension/dist"
      }
    }
  }
}

{
  "mcpServers": {
    "chrome-extension-tester": {
      "command": "npx",
      "args": ["-y", "chrome-extension-tester-mcp"]
    }
  }
}

Example agent workflow

After the MCP server is connected, your AI can run a loop like this:

1. launch_browser  →  extensionPath: "dist", url: "https://example.com"
2. take_extension_screenshot  →  filename: "docs/screenshots/check.png"
3. get_browser_logs  →  inspect errors
4. click_element  →  selector: "#open-popup"
5. close_browser  →  when done

For AI agents

If you are an AI assistant connected to this MCP server, follow this playbook:

Visual changes (CSS, layout, popup UI)

1. Apply code changes and build the extension.
2. Call launch_browser with extensionPath pointing at the build output (e.g. dist/).
3. Call take_extension_screenshot with a descriptive path under docs/screenshots/.
4. Inspect the image; iterate until the UI matches intent.

Runtime errors

1. Reproduce in the launched browser.
2. Call get_browser_logs and look for CSP violations, MV3 service worker errors, or message-passing failures.

Always call close_browser when finished to free resources.

Development (from source)

git clone https://github.com/heyitschien/chrome-extension-tester-mcp.git
cd chrome-extension-tester-mcp
npm install
npm run build
node dist/index.js

For local MCP testing in Cursor, point the command at your build:

{
  "command": "node",
  "args": ["/absolute/path/to/chrome-extension-tester-mcp/dist/index.js"]
}

GitHub repository setup

When you publish or fork this repo, we recommend:

Topics (Settings → General → Topics):

mcp, model-context-protocol, chrome-extension, playwright, cursor, ai, devtools, browser-automation, manifest-v3

Social preview: upload docs/assets/banner.png under Settings → General → Social preview.

Pinned README sections: the banner and workflow diagram above are optimized for GitHub’s dark and light themes.

Legal

• Licensed under the MIT License.
• Uses Playwright (Apache 2.0) for browser automation.
• Chromium is downloaded by Playwright on first run; see Playwright’s license terms.

Contributing

We welcome issues and pull requests! Please read CONTRIBUTING.md and our Code of Conduct first.

Found a security issue? See SECURITY.md — please do not open a public issue.

Author

@heyitschien

If this saves you time, consider starring the repo — it helps other developers find it.

_{Built for developers who ship Chrome Extensions with AI assistants.}