에이전트웹서치 MCP 설치·사용법 — API 키 없이 Chrome CDP로 네이버

Q: Chrome이 반드시 열려 있어야 하나요?

네, MCP 서버가 동작하는 동안 Chrome이 --remote-debugging-port=9222 옵션으로 실행된 상태여야 합니다. Chrome을 닫으면 CDP 연결이 끊겨 검색 도구를 사용할 수 없습니다.

Q: Cursor에도 동일하게 설정할 수 있나요?

네, Cursor의 MCP 설정 파일(.cursor/mcp.json)에 동일한 서버 블록을 추가하면 됩니다. 설정 형식은 Claude Desktop과 같습니다.

AgentWebSearch-MCP는 API 키 없이 Chrome DevTools Protocol(CDP)로 네이버·구글·Brave를 병렬 검색하는 MCP 서버입니다. 별도의 유료 검색 API 구독 없이 Claude Desktop이나 Cursor에서 실시간 웹 검색 결과를 AI 워크플로우에 바로 연결할 수 있습니다. 이 가이드를 따라가면 30분 안에 Claude가 한국어 웹 검색을 수행하도록 설정할 수 있습니다.

왜 API 키 없는 웹 검색 MCP가 필요한가

대부분의 웹 검색 MCP 서버는 Serpapi·Bing Search API·Brave Search API 등 별도의 외부 서비스 계정과 유료 API 키를 요구합니다. 한국 서비스인 네이버 검색은 공식 API가 일별 쿼터와 심사가 필요해 빠르게 프로토타입을 만들기 어렵습니다.

AgentWebSearch-MCP는 이 문제를 다르게 접근합니다. 이미 설치된 Chrome을 원격 디버깅 포트로 제어해 실제 사용자처럼 검색 페이지를 열고 결과를 스크레이핑합니다. 덕분에 API 키 발급 절차 없이 네이버, 구글, Brave를 병렬로 검색할 수 있습니다.

Claude Desktop
    │  MCP stdio
    ▼
AgentWebSearch-MCP 서버 (Python)
    │  Chrome DevTools Protocol (CDP, port 9222)
    ▼
Google Chrome (원격 디버깅 모드)
    │
    ├─▶ 네이버 검색 결과
    ├─▶ 구글 검색 결과
    └─▶ Brave 검색 결과

사전 준비물

항목	버전/비고
Google Chrome(또는 Chromium)	최신 안정 버전 권장
Python	3.10 이상
uv (Python 패키지 매니저)	`pip install uv` 또는 공식 설치 스크립트
Git	저장소 클론용
Claude Desktop 또는 Cursor	MCP 클라이언트

단계별 설치 방법

1단계 — 저장소 클론 및 의존성 설치

먼저 GitHub 저장소를 로컬에 내려받습니다.

git clone https://github.com/insung8150/AgentWebSearch-MCP
cd AgentWebSearch-MCP

이후 uv로 의존성을 설치합니다.

uv pip install -e .

pip를 선호한다면 pip install -e .도 동작합니다. 설치가 완료되면 agentwebsearch-mcp 실행 파일(또는 Python 모듈)이 등록됩니다.

2단계 — Chrome을 원격 디버깅 모드로 실행

MCP 서버가 Chrome을 제어하려면 CDP 포트가 열려 있어야 합니다.

macOS

open -a "Google Chrome" --args --remote-debugging-port=9222

Linux

google-chrome --remote-debugging-port=9222

Windows(PowerShell)

Start-Process "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

브라우저 주소창에 http://localhost:9222/json을 입력했을 때 JSON 응답이 오면 CDP가 정상적으로 열린 것입니다.

3단계 — Claude Desktop 설정 파일에 MCP 서버 등록

Claude Desktop의 설정 파일 위치는 운영체제마다 다릅니다.

OS	경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

설정 파일을 열고 mcpServers 블록에 아래 내용을 추가합니다. 저장소를 클론한 경로(/path/to/AgentWebSearch-MCP)는 실제 경로로 바꿔 주세요.

{
  "mcpServers": {
    "agentwebsearch-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AgentWebSearch-MCP",
        "run",
        "agentwebsearch-mcp"
      ]
    }
  }
}

참고: Python을 직접 사용하는 경우 command를 python으로, args를 ["-m", "agentwebsearch_mcp"] 형식으로 조정하세요. 정확한 모듈·스크립트 이름은 저장소 README를 확인하세요.

4단계 — Cursor에 등록하는 경우

Cursor를 사용한다면 프로젝트 루트 또는 홈 디렉터리의 .cursor/mcp.json 파일에 동일한 블록을 추가합니다.

{
  "mcpServers": {
    "agentwebsearch-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/AgentWebSearch-MCP",
        "run",
        "agentwebsearch-mcp"
      ]
    }
  }
}

5단계 — Claude Desktop 재시작 및 연결 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다(macOS는 메뉴 바 아이콘까지 Quit). 재시작 후 채팅 입력창 근처의 도구 아이콘을 누르면 AgentWebSearch-MCP가 목록에 나타나야 합니다.

6단계 — 첫 번째 네이버 검색 실행

Claude 채팅창에 다음처럼 입력해 보세요.

네이버에서 "MCP 서버 한국어 검색" 키워드로 검색해서 상위 5개 결과를 요약해줘.

Claude가 AgentWebSearch-MCP 도구를 호출해 Chrome을 통해 실제 검색 결과를 가져온 뒤 요약해 드립니다.

흔한 오류와 해결법

오류: “CDP 연결 실패” 또는 “Connection refused”

Chrome이 9222 포트로 실행되지 않은 경우입니다. 2단계의 명령어로 Chrome을 다시 시작하세요. 일반 실행된 Chrome 인스턴스는 CDP를 지원하지 않으므로, 기존 Chrome을 종료하고 디버깅 모드로 새로 실행해야 합니다.

오류: 도구가 Claude 목록에 나타나지 않음

claude_desktop_config.json의 JSON 문법 오류(쉼표, 중괄호 누락)를 확인합니다.
경로(/path/to/AgentWebSearch-MCP)가 실제 클론 경로와 일치하는지 확인합니다.
Claude Desktop을 트레이까지 완전히 종료 후 재시작합니다.

오류: uv 명령을 찾을 수 없음

pip install uv

설치 후 터미널을 재시작하거나 source ~/.zshrc(또는 ~/.bashrc)를 실행해 PATH를 갱신합니다.

검색 결과가 빈 값으로 반환됨

로그인이 필요한 결과를 가져오려 하거나, 검색 엔진이 CDP 접근을 차단한 경우입니다. Chrome에서 직접 해당 검색을 시도해 결과가 나오는지 먼저 확인하세요.

자주 묻는 질문

API 키가 정말 필요 없나요?

네, 필요 없습니다. AgentWebSearch-MCP는 Chrome DevTools Protocol(CDP)을 통해 실제 브라우저를 원격 제어해 검색을 수행하기 때문에 별도의 검색 API 키가 필요하지 않습니다.

Chrome이 반드시 열려 있어야 하나요?

네, MCP 서버가 동작하는 동안 Chrome이 --remote-debugging-port=9222 옵션으로 실행된 상태여야 합니다. Chrome을 닫으면 CDP 연결이 끊겨 검색 도구를 사용할 수 없습니다.

Cursor에도 동일하게 설정할 수 있나요?

네, Cursor의 MCP 설정 파일(.cursor/mcp.json)에 동일한 서버 블록을 추가하면 됩니다. 설정 형식은 Claude Desktop과 같습니다.

네이버 외에 어떤 검색 엔진을 지원하나요?

스펙에 따르면 네이버, 구글, Brave를 병렬로 검색할 수 있습니다. 구체적인 도구 이름과 파라미터는 저장소의 README를 확인하세요.

Windows에서도 동작하나요?

저장소에서 Windows 지원 여부를 명시적으로 확인하시기 바랍니다. Chrome 원격 디버깅 포트는 운영체제에 무관하게 지원되지만, 실행 경로는 OS마다 다릅니다.

설치 후 도구가 Claude 목록에 안 보여요.

Claude Desktop을 완전히 종료(트레이 아이콘까지) 후 재시작하세요. 그래도 안 보이면 설정 파일 경로와 JSON 문법 오류를 먼저 점검하고, Chrome이 CDP 포트 9222로 실행 중인지 확인하세요.

다음 단계

AgentWebSearch-MCP로 네이버 검색을 Claude에 연결했다면, 한국어 생태계를 더 확장해 보세요.

에이전트웹서치 MCP 서버 상세 페이지 — 도구 목록과 업데이트 내역을 확인하세요.
한국어 맞춤법 검사 MCP — 검색 결과를 정리할 때 네이버 맞춤법 검사기를 함께 활용하면 더 완성도 높은 한국어 문서를 만들 수 있습니다.
네이웍스 MCP 서버 — LINE WORKS·NAVER WORKS와 연동해 메시지, 캘린더, 드라이브를 Claude로 제어하세요.
카카오·네이버 카테고리 전체 보기 — 한국 플랫폼에 특화된 MCP 서버를 모아 볼 수 있습니다.
전체 서버 목록 — 다른 분야의 MCP 서버도 둘러보세요.
내 서버를 등록하고 싶다면 MCP모아에 제출하세요.