list_extensions - Extension Inventory

Purpose: Comprehensive extension status monitoring Technical: Accesses chrome://extensions/ via shadow DOM manipulation Output: Extension metadata, enabled/disabled status, version, error detection Use Case: "List all my Chrome extensions" → Shows development and installed extensions

reload_extension - Development Hot-Reload

Purpose: Streamlined extension development workflow Technical: Finds extensions by name/partial match, triggers reload via Chrome extension API Output: Confirmation of reload success/failure with error details Use Case: "Reload my ad-blocker extension" → Instantly applies code changes

inspect_service_worker - Debug Integration

Purpose: Deep debugging of extension background processes Technical: Opens DevTools for service workers, supports Manifest V2/V3 architectures Output: Direct DevTools access to extension console, network, sources Use Case: "Debug why my content script isn't working" → Opens debugging interface

Auto-load Development Extension

Add to ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-extension": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp-for-extension@latest",
        "--loadExtension=/path/to/your/extension"
      ],
      "env": {}
    }
  }
}

⚠️ Note: --loadExtension flag may be deprecated in Chrome 137+. Using system profile (default) is recommended.

Debug Mode

Add to ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-extension": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp-for-extension@latest"],
      "env": {
        "DEBUG": "mcp:*"
      }
    }
  }
}

Custom Chrome Channel

Add to ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-extension": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp-for-extension@latest",
        "--channel=canary"
      ],
      "env": {}
    }
  }
}

Options: stable (default), beta, dev, canary

Isolated Profile Mode

Add to ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-extension": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp-for-extension@latest",
        "--isolated"
      ],
      "env": {}
    }
  }
}

Forces temporary profile instead of system profile.

What Makes This Different

This fork significantly restructures the original Chrome DevTools MCP for extension-focused development:

System Profile Architecture (v0.6.0+)

Zero-Config Design:

// Automatically detects and uses system Chrome profile
if (!isolated && !userDataDir) {
  const systemProfile = detectSystemChromeProfile(channel) || detectAnySystemChromeProfile();

  if (systemProfile) {
    userDataDir = systemProfile.path;  // Direct access, no copying
    usingSystemProfile = true;
  }
}

Profile Paths:

• macOS: ~/Library/Application Support/Google/Chrome
• Windows: %LOCALAPPDATA%\Google\Chrome\User Data
• Linux: ~/.config/google-chrome

Detection Priority:

1. Specified channel (via --channel flag)
2. Fallback: stable → beta → dev → canary
3. Last resort: Creates temporary isolated profile

Extension Loading Architecture

Unconditional Extension Enablement (v0.6.1+):

// Always remove --disable-extensions flag
ignoreDefaultArgs: ['--disable-extensions', '--enable-automation']

Why this design:

• Puppeteer's default --disable-extensions conflicts with extension development
• Previous versions used conditional logic (buggy, removed in v0.6.1)
• Current approach: Always enable all extensions for predictable behavior

Chrome Security Challenges Solved

Chrome 137+ Breaking Changes

• Problem: Chrome 137+ disabled --load-extension in automation contexts
• Solution: Added --disable-features=DisableLoadExtensionCommandLineSwitch bypass
• Impact: Development extensions can still be loaded via CLI flags

Automation Detection Bypass

• Problem: Chrome blocks many operations when detecting automated control
• Solution: --disable-blink-features=AutomationControlled for real-world testing
• Use Case: Google login, OAuth flows, Web Store submission

Profile Management Strategy

• Default: Direct system profile access (no copying, instant sync)
• Fallback: Temporary profile with bookmarks copy (when Chrome is already running)
• Override: --isolated flag for completely separate profile

Architecture Diagram

Extension Development Flow:
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ AI Assistant    │───▶│ MCP Server       │───▶│ Chrome Browser  │
│ (Claude/Cursor) │    │ (Extension Tools)│    │ + Extensions    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │                         │
                              ▼                         ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │ Web Store        │    │ System Profile  │
                       │ Automation       │    │ (Direct Access) │
                       └──────────────────┘    └─────────────────┘

Web Store Automation Tools

Submission Workflow (submit_to_webstore)

1. Manifest Validation: Manifest V3 compliance, permission security analysis
2. Package Creation: ZIP generation with optimized compression, development file exclusion
3. Store Listing: Auto-generated descriptions based on manifest permissions
4. Browser Automation: Login flow, form population, file upload, error detection

Screenshot Generation (generate_extension_screenshots)

• Primary: 1280x800 (Web Store requirement)
• Promotional Tiles: Small (440x280), Large (920x680), Marquee (1400x560)
• Smart Capture: Extension popup, options page, in-context usage

Manifest Validation System

interface ManifestValidation {
  required: string[];      // name, version, manifest_version
  warnings: string[];      // description length, icon sizes
  security: string[];      // dangerous permissions analysis
  suggestions: string[];   // optimization recommendations
}

Validation Features:

• Manifest V3 compliance enforcement
• Permission analysis with security implications
• Icon size recommendations (16x16, 48x48, 128x128)
• Service worker file verification
• Host permission optimization suggestions

Added Dependencies

• archiver (7.0.1): ZIP package creation for extension submission
• puppeteer-core (24.22.3): Chrome automation with extension support
• @modelcontextprotocol/sdk (1.18.1): MCP server implementation

MCP Server Coexistence

• Server Name: chrome-devtools-extension (vs original chrome-devtools)
• Package Name: chrome-devtools-mcp-for-extension
• Purpose: Allows both servers to run simultaneously for different use cases

Supported Extension Types

• Manifest V3: Full support (recommended)
• Service Workers: Background script debugging
• Content Scripts: Page interaction testing
• Popup Extensions: UI testing and screenshots
• Options Pages: Settings interface validation

Browser Compatibility

• Chrome: Primary target (latest stable)
• Chrome Canary: Development testing
• Chromium: Community builds
• Edge: Chromium-based versions

Technical Requirements

• Node.js: 22.12.0+ (for latest Chrome DevTools Protocol)
• Chrome: Any version with extension support
• Storage: ~50MB for dependencies
• Network: Required for Web Store automation

Extension Loading Capabilities

• Startup Loading: Extensions loaded at Chrome startup via --loadExtension
• System Extensions: Auto-loads all extensions from Chrome profile (default)
• Manual Reloading: Update extensions via reload_extension MCP tool
• Multi-Extension: Support for multiple extensions simultaneously

⚠️ Note: Runtime extension installation not supported. Extensions must be loaded at startup.

Security & Privacy Considerations

• System Profile Access: Uses system Chrome profile by default (includes cookies, sessions, history, bookmarks)
• Profile Isolation: Use --isolated flag for temporary profile without personal data
• Extension Sandboxing: Extension permissions are sandboxed per Chrome security model
• Web Store Auth: Uses standard Google OAuth flow (no credentials stored)

⚠️ Warning: When using system profile, the MCP server has access to all data in your Chrome profile. Use --isolated mode for testing sensitive operations.

Extension Not Loading

Check manifest.json:

"List extensions and show any errors"

Verify extension is in correct directory:

• Manifest must be at root: /your-extension/manifest.json
• Not: /your-extension/dist/manifest.json

Solution:

Update ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-extension": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp-for-extension@latest",
        "--loadExtension=/correct/path"
      ],
      "env": {}
    }
  }
}

Service Worker Not Inspecting

Extension may not be active:

"List extensions"  // Check if enabled
"Reload my-extension"  // Restart extension

DevTools window not appearing:

• Service worker only runs when needed
• Trigger extension action first (click popup, run content script)

Web Store Submission Fails

Manifest V3 compliance:

"Validate my manifest for Web Store compliance"

Common issues:

• Missing required icons (16x16, 48x48, 128x128)
• Invalid permissions (host_permissions format)
• Service worker not specified

Extensions Disabled After Chrome Update

Chrome 137+ breaking change:

• --load-extension may be restricted in newer Chrome versions
• Solution: Use system profile (default) instead of --loadExtension flag

System Extensions Loading (v0.7.1+)

How does the MCP server handle Chrome extensions?

The MCP server uses an isolated profile with --load-extension to provide system extensions while maintaining independence:

Default Behavior

• ✅ Independent Chrome Instance: Runs separately from your main Chrome browser
• ✅ System Extensions Loaded: Your installed Chrome extensions are automatically loaded via --load-extension
• ✅ Concurrent Usage: Works alongside your regular Chrome browser without conflicts
• 🔒 Isolated Login State: First launch requires Google login (for security)
• 🔒 Isolated Profile: Uses ~/.cache/chrome-devtools-mcp/chrome-profile/

What Works

• ✅ Extensions: All system Chrome extensions are dynamically loaded
• ✅ Bookmarks: Accessible via MCP tools (list_bookmarks, navigate_bookmark)
• ✅ Login State: Preserved in isolated profile after first login

What Doesn't Work

• ❌ Bookmarks in Browser UI: Not displayed in browser bookmarks bar (use MCP tools instead)
• ❌ Shared Login State: System Chrome login state is not shared (first login required)

Profile Location

~/.cache/chrome-devtools-mcp/chrome-profile/
└── Default/
    ├── Cookies        (isolated)
    ├── Login Data     (isolated)
    └── ...            (all files isolated)

First Launch

• Extensions: Automatically loaded from system Chrome via --load-extension
• Google Login required: You'll need to log in once (login state is isolated for security)
• Subsequent launches: Login state is preserved in the isolated profile

Isolated Mode (No Extensions)

To run without any extensions:

npx chrome-devtools-mcp-for-extension@latest --isolated