claude-in-chrome-troubleshooting

name	claude-in-chrome-troubleshooting
description	Diagnoses macOS Claude in Chrome MCP native-host conflicts between Claude.app (Cowork) and Claude Code CLI sockets. Use when mcp__claude-in-chrome__* tools fail, return Browser extension is not connected, or behave erratically after updates. Not for Linux or Windows hosts, general Chrome automation, Claude.app desktop bugs, network outages, or Chrome Web Store install issues.
version	1.0.1
risk	critical
source	community

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, $TMPDIR)
• 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)

Prerequisites

• macOS host (this skill is macOS-only; paths and commands use osascript, getconf DARWIN_USER_TEMP_DIR, and ~/Library/Application Support/)
• Google Chrome installed
• Claude in Chrome extension installed from the Chrome Web Store
• Claude Code CLI and/or Claude.app installed
• Shell access (bash/zsh)

Procedure

Step 1: Identify the Primary Conflict

Claude.app (Cowork) and Claude Code CLI each register a competing native messaging host in Chrome. They use incompatible socket formats and locations. Only one can be active at a time.

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)

Both register native messaging configs in Chrome:

• com.anthropic.claude_browser_extension.json → Claude.app helper
• com.anthropic.claude_code_browser_extension.json → Claude Code wrapper

If the wrong config is active, the wrong binary runs, creating sockets in a format/location the MCP client doesn't expect. Result: "Browser extension is not connected" even though everything appears to be running.

Step 2: Run 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*.json

Step 3: Disable the Conflicting 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.json

If 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.disabled

You cannot use both simultaneously. Pick one and disable the other.

Step 4: Toggle Script (Optional)

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" 
         
         
    
         
         -la /com.anthropic*.json* 2>/dev/null
    
}

Usage: chrome-mcp-toggle then restart Chrome (and Claude Code if switching to CLI).

Step 5: Full Reset Procedure (Claude Code CLI)

If quick fixes don't work, perform a full reset:

# 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 Code

Step 6: Diagnostic Deep Dive

If the above steps don't resolve the issue, run the full diagnostic:

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)"

Pitfalls

1. MCP connects at startup only. If the browser bridge wasn't ready when Claude Code started, the connection will fail for the entire session. The fix is: ensure Chrome + extension are running with correct config, THEN restart Claude Code. Do not skip the Claude Code restart.

2. Multiple Chrome Profiles. If the Claude extension is installed in multiple Chrome profiles, each spawns its own native host and socket, causing confusion. Fix: Only enable the Claude extension in ONE Chrome profile.

3. Multiple Claude Code Sessions. Running multiple Claude Code instances causes socket conflicts. Fix: Only run one Claude Code session at a time, or use /mcp to reconnect after closing other sessions.

4. Hardcoded Version in Wrapper. The wrapper at ~/.claude/chrome/chrome-native-host may have a hardcoded version that becomes stale after updates.

   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 latest
   

   Fix: Use the dynamic version wrapper shown in the Full Reset Procedure (Step 5).

5. 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)}"
   

6. Cannot use both hosts simultaneously. Claude.app (Cowork) and Claude Code CLI native hosts are mutually exclusive. You must disable one for the other to work.

Verification

After applying fixes, verify the connection is working:

# 1. Verify correct native host is running (Claude Code CLI)
ps aux | grep chrome-native-host | grep -v grep
# Expected: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 2. Verify socket exists (Claude Code CLI)
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# Expected: socket file exists and is not stale

# 3. Verify only one config is active
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json
# Expected: only one .json file (the other should be .json.disabled)

# 4. Verify TMPDIR is set
echo $TMPDIR
# Expected: /var/folders/XX/.../T/

# 5. Test MCP tool from Claude Code
# Call any mcp__claude-in-chrome__* tool — should return successfully
# instead of "Browser extension is not connected"

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)

Related Skills

• Any skill that uses mcp__claude-in-chrome__* tools for browser automation may trigger this troubleshooting skill when those tools fail.

---

Original skill by @jeffzwang from @ExaAILabs. Enhanced and updated for current versions of Claude Desktop and Claude Code.