Chrome MCP Troubleshooting
Trail of BitsOfficialPublished by Trail of Bits
- Skill
- Workflow
- Software development
- CC-BY-SA-4.0
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a systematic approach to diagnosing and fixing 'Browser extension is not connected' errors when using Claude MCP tools. It specifically addresses conflicts between the Claude.app (Cowork) and Claude Code CLI native messaging hosts, which use incompatible socket formats. The guide includes diagnostic commands, a toggle script for switching between environments, and a full reset procedure to restore browser automation functionality.
What it does
- Identifies conflicts between Claude.app and Claude Code native messaging hosts.
- Provides a toggle script to switch between Claude.app and Claude Code browser automation.
- Offers a full reset procedure to clean up stale sockets and native host configurations.
- Includes diagnostic commands to verify running processes, socket locations, and active configurations.
- Explains how to correctly configure the native host wrapper for Claude Code.
- Highlights common pitfalls like multiple Chrome profiles or stale version paths.
When to use it
- When MCP tools return 'Browser extension is not connected' errors.
- When browser automation behaves erratically or times out.
- After updating Claude Code or Claude.app.
- When switching between Claude Code CLI and Claude.app (Cowork) usage.
- When native host processes are running but MCP tools fail to communicate.
Advantages
- Resolves the primary conflict caused by competing native messaging host configurations.
- Provides a clear, step-by-step path to restore connectivity.
- Includes automated diagnostic and toggle scripts for efficiency.
- Ensures consistent behavior by enforcing single-profile and single-session usage.
Usage examples
- “My Claude Code browser tools are failing with a connection error, how do I fix it?”
- The agent will guide you through disabling the Claude.app native host config and resetting the Claude Code socket to restore connectivity.
- “How can I switch from using Cowork in Claude.app to using Claude Code CLI for browser automation?”
- The agent will provide the toggle script or manual steps to disable the Claude.app native messaging config and enable the Claude Code configuration.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/trailofbits/chrome-mcp-troubleshooting/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip chrome-mcp-troubleshooting.zip -d .agents/skills
Documentation by Trail of Bits
Claude in Chrome MCP Troubleshooting
Use this skill when Claude in Chrome MCP tools fail to connect or work unreliably.
When to Use
mcp__claude-in-chrome__*tools fail with "Browser extension is not connected"Browser automation works erratically or times out
After updating Claude Code or Claude.app
When switching between Claude Code CLI and Claude.app (Cowork)
Native host process is running but MCP tools still fail
When NOT to Use
Linux or Windows users - This skill covers macOS-specific paths and tools (
~/Library/Application Support/,osascript)General Chrome automation issues unrelated to the Claude extension
Claude.app desktop issues (not browser-related)
Network connectivity problems
Chrome extension installation issues (use Chrome Web Store support)
The Claude.app vs Claude Code Conflict (Primary Issue)
Background: When Claude.app added Cowork support (browser automation from the desktop app), it introduced a competing native messaging host that conflicts with Claude Code CLI.
Two Native Hosts, Two Socket Formats
| Component | Native Host Binary | Socket Location |
|---|---|---|
| Claude.app (Cowork) | /Applications/Claude.app/Contents/Helpers/chrome-native-host | /tmp/claude-mcp-browser-bridge-$USER/<PID>.sock |
| Claude Code CLI | ~/.local/share/claude/versions/<version> --chrome-native-host | $TMPDIR/claude-mcp-browser-bridge-$USER (single file) |
Why They Conflict
Both register native messaging configs in Chrome:
com.anthropic.claude_browser_extension.json→ Claude.app helpercom.anthropic.claude_code_browser_extension.json→ Claude Code wrapper
Chrome extension requests a native host by name
If the wrong config is active, the wrong binary runs
The wrong binary creates sockets in a format/location the MCP client doesn't expect
Result: "Browser extension is not connected" even though everything appears to be running
The Fix: Disable Claude.app's Native Host
If you use Claude Code CLI for browser automation (not Cowork):
# Disable the Claude.app native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled
# Ensure the Claude Code config exists and points to the wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.jsonIf you use Cowork (Claude.app) for browser automation:
# Disable the Claude Code native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.disabledYou cannot use both simultaneously. Pick one and disable the other.
Toggle Script
Add this to ~/.zshrc or run directly:
chrome-mcp-toggle() {
local CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
local CLAUDE_APP="$CONFIG_DIR/com.anthropic.claude_browser_extension.json"
local CLAUDE_CODE="$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json"
if [[ -f "$CLAUDE_APP" && ! -f "$CLAUDE_APP.disabled" ]]; then
# Currently using Claude.app, switch to Claude Code
mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
[[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
echo "Switched to Claude Code CLI"
echo "Restart Chrome and Claude Code to apply"
elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
# Currently using Claude Code, switch to Claude.app
mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
[[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
echo "Switched to Claude.app (Cowork)"
echo "Restart Chrome to apply"
else
echo "Current state unclear. Check configs:"
ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
fi
}Usage: chrome-mcp-toggle then restart Chrome (and Claude Code if switching to CLI).
Quick Diagnosis
# 1. Which native host binary is running?
ps aux | grep chrome-native-host | grep -v grep
# Claude.app: /Applications/Claude.app/Contents/Helpers/chrome-native-host
# Claude Code: ~/.local/share/claude/versions/X.X.X --chrome-native-host
# 2. Where is the socket?
# For Claude Code (single file in TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
# For Claude.app (directory with PID files):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
# 3. What's the native host connected to?
lsof -U 2>&1 | grep claude-mcp-browser-bridge
# 4. Which configs are active?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.jsonCritical Insight
MCP connects at startup. If the browser bridge wasn't ready when Claude Code started, the connection will fail for the entire session. The fix is usually: ensure Chrome + extension are running with correct config, THEN restart Claude Code.
Full Reset Procedure (Claude Code CLI)
# 1. Ensure correct config is active
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled 2>/dev/null
# 2. Update the wrapper to use latest Claude Code version
cat > ~/.claude/chrome/chrome-native-host << 'EOF'
#!/bin/bash
LATEST=$(ls -t ~/.local/share/claude/versions/ 2>/dev/null | head -1)
exec "$HOME/.local/share/claude/versions/$LATEST" --chrome-native-host
EOF
chmod +x ~/.claude/chrome/chrome-native-host
# 3. Kill existing native host and clean sockets
pkill -f chrome-native-host
rm -rf /tmp/claude-mcp-browser-bridge-$USER/
rm -f "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# 4. Restart Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"
# 5. Wait for Chrome, click Claude extension icon
# 6. Verify correct native host is running
ps aux | grep chrome-native-host | grep -v grep
# Should show: ~/.local/share/claude/versions/X.X.X --chrome-native-host
# 7. Verify socket exists
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# 8. Restart Claude CodeOther Common Causes
Multiple Chrome Profiles
If you have the Claude extension installed in multiple Chrome profiles, each spawns its own native host and socket. This can cause confusion.
Fix: Only enable the Claude extension in ONE Chrome profile.
Multiple Claude Code Sessions
Running multiple Claude Code instances can cause socket conflicts.
Fix: Only run one Claude Code session at a time, or use /mcp to reconnect after closing other sessions.
Hardcoded Version in Wrapper
The wrapper at ~/.claude/chrome/chrome-native-host may have a hardcoded version that becomes stale after updates.
Diagnosis:
cat ~/.claude/chrome/chrome-native-host
# Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Good: Uses $(ls -t ...) to find latestFix: Use the dynamic version wrapper shown in the Full Reset Procedure above.
TMPDIR Not Set
Claude Code expects TMPDIR to be set to find the socket.
# Check
echo $TMPDIR
# Should show: /var/folders/XX/.../T/
# Fix: Add to ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"Diagnostic Deep Dive
echo "=== Native Host Binary ==="
ps aux | grep chrome-native-host | grep -v grep
echo -e "\n=== Socket (Claude Code location) ==="
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
echo -e "\n=== Socket (Claude.app location) ==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
echo -e "\n=== Native Host Open Files ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"
echo -e "\n=== Active Native Messaging Configs ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null
echo -e "\n=== Custom Wrapper Contents ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"
echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"File Reference
| File | Purpose |
|---|---|
~/.claude/chrome/chrome-native-host | Custom wrapper script for Claude Code |
/Applications/Claude.app/Contents/Helpers/chrome-native-host | Claude.app (Cowork) native host |
~/.local/share/claude/versions/<version> | Claude Code binary (run with --chrome-native-host) |
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json | Config for Claude.app native host |
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json | Config for Claude Code native host |
$TMPDIR/claude-mcp-browser-bridge-$USER | Socket file (Claude Code) |
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock | Socket files (Claude.app) |
Summary
Primary issue: Claude.app (Cowork) and Claude Code use different native hosts with incompatible socket formats
Fix: Disable the native messaging config for whichever one you're NOT using
After any fix: Must restart Chrome AND Claude Code (MCP connects at startup)
One profile: Only have Claude extension in one Chrome profile
One session: Only run one Claude Code instance
Original skill by @jeffzwang from @ExaAILabs. Enhanced and updated for current versions of Claude Desktop and Claude Code.
Files
- ATTRIBUTION.mdAdded by AutoGineer972 B
- LICENSELicence file added by AutoGineer19.7 KiB
- SKILL.md10.0 KiB
- agents/openai.yaml242 B
- assets/trail-of-bits-mark.svg3.0 KiB
SKILL.md
Claude in Chrome MCP Troubleshooting
Use this skill when Claude in Chrome MCP tools fail to connect or work unreliably.
When to Use
mcp__claude-in-chrome__*tools fail with "Browser extension is not connected"Browser automation works erratically or times out
After updating Claude Code or Claude.app
When switching between Claude Code CLI and Claude.app (Cowork)
Native host process is running but MCP tools still fail
When NOT to Use
Linux or Windows users - This skill covers macOS-specific paths and tools (
~/Library/Application Support/,osascript)General Chrome automation issues unrelated to the Claude extension
Claude.app desktop issues (not browser-related)
Network connectivity problems
Chrome extension installation issues (use Chrome Web Store support)
The Claude.app vs Claude Code Conflict (Primary Issue)
Background: When Claude.app added Cowork support (browser automation from the desktop app), it introduced a competing native messaging host that conflicts with Claude Code CLI.
Two Native Hosts, Two Socket Formats
| Component | Native Host Binary | Socket Location |
|---|---|---|
| Claude.app (Cowork) | /Applications/Claude.app/Contents/Helpers/chrome-native-host | /tmp/claude-mcp-browser-bridge-$USER/<PID>.sock |
| Claude Code CLI | ~/.local/share/claude/versions/<version> --chrome-native-host | $TMPDIR/claude-mcp-browser-bridge-$USER (single file) |
Why They Conflict
Both register native messaging configs in Chrome:
com.anthropic.claude_browser_extension.json→ Claude.app helpercom.anthropic.claude_code_browser_extension.json→ Claude Code wrapper
Chrome extension requests a native host by name
If the wrong config is active, the wrong binary runs
The wrong binary creates sockets in a format/location the MCP client doesn't expect
Result: "Browser extension is not connected" even though everything appears to be running
The Fix: Disable Claude.app's Native Host
If you use Claude Code CLI for browser automation (not Cowork):
# Disable the Claude.app native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled
# Ensure the Claude Code config exists and points to the wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.jsonIf you use Cowork (Claude.app) for browser automation:
# Disable the Claude Code native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.disabledYou cannot use both simultaneously. Pick one and disable the other.
Toggle Script
Add this to ~/.zshrc or run directly:
chrome-mcp-toggle() {
local CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
local CLAUDE_APP="$CONFIG_DIR/com.anthropic.claude_browser_extension.json"
local CLAUDE_CODE="$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json"
if [[ -f "$CLAUDE_APP" && ! -f "$CLAUDE_APP.disabled" ]]; then
# Currently using Claude.app, switch to Claude Code
mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
[[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
echo "Switched to Claude Code CLI"
echo "Restart Chrome and Claude Code to apply"
elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
# Currently using Claude Code, switch to Claude.app
mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
[[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
echo "Switched to Claude.app (Cowork)"
echo "Restart Chrome to apply"
else
echo "Current state unclear. Check configs:"
ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
fi
}Usage: chrome-mcp-toggle then restart Chrome (and Claude Code if switching to CLI).
Quick Diagnosis
# 1. Which native host binary is running?
ps aux | grep chrome-native-host | grep -v grep
# Claude.app: /Applications/Claude.app/Contents/Helpers/chrome-native-host
# Claude Code: ~/.local/share/claude/versions/X.X.X --chrome-native-host
# 2. Where is the socket?
# For Claude Code (single file in TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
# For Claude.app (directory with PID files):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
# 3. What's the native host connected to?
lsof -U 2>&1 | grep claude-mcp-browser-bridge
# 4. Which configs are active?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.jsonCritical Insight
MCP connects at startup. If the browser bridge wasn't ready when Claude Code started, the connection will fail for the entire session. The fix is usually: ensure Chrome + extension are running with correct config, THEN restart Claude Code.
Full Reset Procedure (Claude Code CLI)
# 1. Ensure correct config is active
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled 2>/dev/null
# 2. Update the wrapper to use latest Claude Code version
cat > ~/.claude/chrome/chrome-native-host << 'EOF'
#!/bin/bash
LATEST=$(ls -t ~/.local/share/claude/versions/ 2>/dev/null | head -1)
exec "$HOME/.local/share/claude/versions/$LATEST" --chrome-native-host
EOF
chmod +x ~/.claude/chrome/chrome-native-host
# 3. Kill existing native host and clean sockets
pkill -f chrome-native-host
rm -rf /tmp/claude-mcp-browser-bridge-$USER/
rm -f "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# 4. Restart Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"
# 5. Wait for Chrome, click Claude extension icon
# 6. Verify correct native host is running
ps aux | grep chrome-native-host | grep -v grep
# Should show: ~/.local/share/claude/versions/X.X.X --chrome-native-host
# 7. Verify socket exists
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# 8. Restart Claude CodeOther Common Causes
Multiple Chrome Profiles
If you have the Claude extension installed in multiple Chrome profiles, each spawns its own native host and socket. This can cause confusion.
Fix: Only enable the Claude extension in ONE Chrome profile.
Multiple Claude Code Sessions
Running multiple Claude Code instances can cause socket conflicts.
Fix: Only run one Claude Code session at a time, or use /mcp to reconnect after closing other sessions.
Hardcoded Version in Wrapper
The wrapper at ~/.claude/chrome/chrome-native-host may have a hardcoded version that becomes stale after updates.
Diagnosis:
cat ~/.claude/chrome/chrome-native-host
# Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# Good: Uses $(ls -t ...) to find latestFix: Use the dynamic version wrapper shown in the Full Reset Procedure above.
TMPDIR Not Set
Claude Code expects TMPDIR to be set to find the socket.
# Check
echo $TMPDIR
# Should show: /var/folders/XX/.../T/
# Fix: Add to ~/.zshrc
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"Diagnostic Deep Dive
echo "=== Native Host Binary ==="
ps aux | grep chrome-native-host | grep -v grep
echo -e "\n=== Socket (Claude Code location) ==="
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1
echo -e "\n=== Socket (Claude.app location) ==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1
echo -e "\n=== Native Host Open Files ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"
echo -e "\n=== Active Native Messaging Configs ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null
echo -e "\n=== Custom Wrapper Contents ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"
echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"File Reference
| File | Purpose |
|---|---|
~/.claude/chrome/chrome-native-host | Custom wrapper script for Claude Code |
/Applications/Claude.app/Contents/Helpers/chrome-native-host | Claude.app (Cowork) native host |
~/.local/share/claude/versions/<version> | Claude Code binary (run with --chrome-native-host) |
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json | Config for Claude.app native host |
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json | Config for Claude Code native host |
$TMPDIR/claude-mcp-browser-bridge-$USER | Socket file (Claude Code) |
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock | Socket files (Claude.app) |
Summary
Primary issue: Claude.app (Cowork) and Claude Code use different native hosts with incompatible socket formats
Fix: Disable the native messaging config for whichever one you're NOT using
After any fix: Must restart Chrome AND Claude Code (MCP connects at startup)
One profile: Only have Claude extension in one Chrome profile
One session: Only run one Claude Code instance
Original skill by @jeffzwang from @ExaAILabs. Enhanced and updated for current versions of Claude Desktop and Claude Code.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Needs: Needs an MCP server
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Trail of Bits
- Publisher
- Trail of Bits (Official)
- Source
- trailofbits/skills · plugins/chrome-mcp-troubleshooting/skills/chrome-mcp-troubleshooting · commit e4dd0bb
- Licence
- Creative Commons Attribution-ShareAlike 4.0 International (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Trail of Bits or Trail of Bits.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download chrome-mcp-troubleshooting.zip