Chrome MCP 트러블슈팅

Claude in Chrome MCP 트러블슈팅

Claude in Chrome MCP 도구가 연결에 실패하거나 신뢰할 수 없게 작동할 때 이 기술을 사용하세요.

사용 시점

• mcp__claude-in-chrome__* 도구가 "Browser extension is not connected" 오류와 함께 실패할 때
• 브라우저 자동화가 불규칙하게 작동하거나 타임아웃될 때
• Claude Code 또는 Claude.app을 업데이트한 후
• Claude Code CLI와 Claude.app(Cowork) 사이를 전환할 때
• 네이티브 호스트 프로세스가 실행 중이지만 MCP 도구가 여전히 실패할 때

사용하지 말아야 할 경우

• Linux 또는 Windows 사용자 - 이 기술은 macOS 특화 경로와 도구(~/Library/Application Support/, osascript)를 다룹니다.
• Claude 확장 프로그램과 관련 없는 일반적인 Chrome 자동화 문제
• Claude.app 데스크톱 문제 (브라우저 관련이 아닌 경우)
• 네트워크 연결 문제
• Chrome 확장 프로그램 설치 문제 (Chrome 웹 스토어 지원 사용)

Claude.app과 Claude Code의 충돌 (주요 문제)

배경: Claude.app에 Cowork 지원(데스크톱 앱에서 브라우저 자동화)이 추가되면서 Claude Code CLI와 충돌하는 경쟁 네이티브 메시징 호스트가 도입되었습니다.

두 네이티브 호스트, 두 소켓 형식

구성 요소	네이티브 호스트 바이너리	소켓 위치
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 (단일 파일)

충돌 원인

1. 두 프로그램 모두 Chrome에 네이티브 메시징 설정을 등록합니다:

   • com.anthropic.claude_browser_extension.json → Claude.app 헬퍼
   • com.anthropic.claude_code_browser_extension.json → Claude Code 래퍼

2. Chrome 확장 프로그램이 이름으로 네이티브 호스트를 요청합니다.

3. 잘못된 설정이 활성화되어 있으면 잘못된 바이너리가 실행됩니다.

4. 잘못된 바이너리가 MCP 클라이언트가 예상하지 못한 형식/위치에 소켓을 생성합니다.

5. 결과: 모든 것이 실행 중인 것처럼 보여도 "Browser extension is not connected" 오류가 발생합니다.

해결 방법: Claude.app의 네이티브 호스트 비활성화

브라우저 자동화에 Claude Code CLI를 사용하는 경우 (Cowork가 아닌 경우):

# Claude.app 네이티브 메시징 설정 비활성화
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

# Claude Code 설정이 존재하고 래퍼를 가리키는지 확인
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json

브라우저 자동화에 Cowork(Claude.app)를 사용하는 경우:

# Claude Code 네이티브 메시징 설정 비활성화
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

두 개를 동시에 사용할 수 없습니다. 하나를 선택하고 다른 하나를 비활성화하세요.

전환 스크립트

~/.zshrc에 추가하거나 직접 실행하세요:

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
        # 현재 Claude.app 사용 중, Claude Code로 전환
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Claude Code CLI로 전환됨"
        echo "적용하려면 Chrome과 Claude Code를 다시 시작하세요."
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # 현재 Claude Code 사용 중, Claude.app으로 전환
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Claude.app (Cowork)으로 전환됨"
        echo "적용하려면 Chrome을 다시 시작하세요."
    else
        echo "현재 상태를 확인할 수 없습니다. 설정을 확인하세요:"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}

사용법: chrome-mcp-toggle 실행 후 Chrome을 다시 시작하고 (CLI로 전환하는 경우 Claude Code도 다시 시작)하세요.

빠른 진단

# 1. 어떤 네이티브 호스트 바이너리가 실행 중인가요?
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. 소켓은 어디에 있나요?
# Claude Code의 경우 (TMPDIR 내 단일 파일):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# Claude.app의 경우 (PID 파일이 있는 디렉토리):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. 네이티브 호스트가 무엇에 연결되어 있나요?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. 어떤 설정이 활성화되어 있나요?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json

중요한 통찰

MCP는 시작 시 연결됩니다. Claude Code가 시작될 때 브라우저 브리지가 준비되지 않았다면 해당 세션 전체에서 연결이 실패합니다. 해결 방법은 일반적으로: 올바른 설정으로 Chrome과 확장 프로그램이 실행 중인지 확인한 후, Claude Code를 다시 시작하는 것입니다.

전체 리셋 절차 (Claude Code CLI)

# 1. 올바른 설정이 활성화되어 있는지 확인
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. 최신 Claude Code 버전을 사용하도록 래퍼 업데이트
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. 기존 네이티브 호스트 종료 및 소켓 정리
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. Chrome 다시 시작
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Chrome이 시작될 때까지 기다린 후, Claude 확장 프로그램 아이콘 클릭

# 6. 올바른 네이티브 호스트가 실행 중인지 확인
ps aux | grep chrome-native-host | grep -v grep
# 다음이 표시되어야 합니다: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. 소켓이 존재하는지 확인
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Claude Code 다시 시작

기타 일반적인 원인

여러 Chrome 프로필

여러 Chrome 프로필에 Claude 확장 프로그램이 설치되어 있으면 각각 자체 네이티브 호스트와 소켓을 생성합니다. 이로 인해 혼란이 발생할 수 있습니다.

해결 방법: 하나의 Chrome 프로필에서만 Claude 확장 프로그램을 활성화하세요.

여러 Claude Code 세션

여러 Claude Code 인스턴스를 실행하면 소켓 충돌이 발생할 수 있습니다.

해결 방법: 한 번에 하나의 Claude Code 세션만 실행하거나, 다른 세션을 닫은 후 /mcp를 사용하여 다시 연결하세요.

래퍼의 하드코딩된 버전

~/.claude/chrome/chrome-native-host의 래퍼에 하드코딩된 버전이 있어 업데이트 후 오래된 버전을 사용할 수 있습니다.

진단:

cat ~/.claude/chrome/chrome-native-host
# 잘못된 예: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
# 올바른 예: $(ls -t ...)를 사용하여 최신 버전 찾기

해결 방법: 위의 전체 리셋 절차에 나와 있는 동적 버전 래퍼를 사용하세요.

TMPDIR이 설정되지 않음

Claude Code는 소켓을 찾기 위해 TMPDIR이 설정되어 있어야 합니다.

# 확인
echo $TMPDIR
# 다음이 표시되어야 합니다: /var/folders/XX/.../T/

# 해결 방법: ~/.zshrc에 추가
export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"

심층 진단

echo "=== 네이티브 호스트 바이너리 ==="
ps aux | grep chrome-native-host | grep -v grep

echo -e "\n=== 소켓 (Claude Code 위치) ==="
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

echo -e "\n=== 소켓 (Claude.app 위치) ==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

echo -e "\n=== 네이티브 호스트 열린 파일 ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== 활성 네이티브 메시징 설정 ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== 사용자 래퍼 내용 ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "사용자 래퍼 없음"

echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "예상 경로: $(getconf DARWIN_USER_TEMP_DIR)"

파일 참조

파일	용도
~/.claude/chrome/chrome-native-host	Claude Code용 사용자 래퍼 스크립트
/Applications/Claude.app/Contents/Helpers/chrome-native-host	Claude.app (Cowork) 네이티브 호스트
~/.local/share/claude/versions/<version>	Claude Code 바이너리 (--chrome-native-host와 함께 실행)
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json	Claude.app 네이티브 호스트 설정
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json	Claude Code 네이티브 호스트 설정
$TMPDIR/claude-mcp-browser-bridge-$USER	소켓 파일 (Claude Code)
/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock	소켓 파일 (Claude.app)

요약

1. 주요 문제: Claude.app (Cowork)과 Claude Code가 호환되지 않는 소켓 형식을 가진 서로 다른 네이티브 호스트를 사용합니다.
2. 해결 방법: 사용하지 않는 쪽의 네이티브 메시징 설정을 비활성화하세요.
3. 수정 후: Chrome과 Claude Code를 모두 다시 시작해야 합니다 (MCP는 시작 시 연결됩니다).
4. 하나의 프로필: 하나의 Chrome 프로필에만 Claude 확장 프로그램을 두세요.
5. 하나의 세션: 한 번에 하나의 Claude Code 인스턴스만 실행하세요.

---

원본 기술: @ExaAILabs의 @jeffzwang 제작. 현재 버전의 Claude Desktop 및 Claude Code에 맞게 개선 및 업데이트됨.