클로드 코드(Claude Code)는 기본적으로 실시간 웹 검색을 하지 않습니다. 코드를 읽고, 파일을 다루고, 셸을 굴리는 데는 강하지만 “오늘 발표된 라이브러리 변경 사항”, “지금 트렌드인 라이브러리 비교” 같은 최신 정보를 직접 못 가져옵니다. 이 빈자리를 가장 깔끔하게 채워 주는 도구가 Gemini Search MCP입니다. 무료 API 키 한 장으로 클로드 코드 안에서 구글 검색 결과를 그라운딩한 답을 받을 수 있습니다. 설치, 키 발급, 실제 사용법까지 한 번에 정리해 드립니다.
목차
Gemini Search MCP가 뭔가요
MCP(Model Context Protocol)는 클로드 코드가 외부 도구에 접근할 수 있도록 표준화된 통로입니다. Gemini Search MCP는 그 통로를 통해 구글 Gemini 모델 + 구글 검색을 호출해 주는 작은 서버입니다. 클로드가 “검색이 필요해 보이는 질문”을 만나면 이 서버를 호출하고, Gemini가 구글 검색 결과를 근거로 답변을 만들어 돌려줍니다.
핵심 가치는 두 가지입니다.
- 실시간 웹 정보: 클로드 자체 학습 시점 이후의 변경, 오늘 뉴스, 새로 나온 라이브러리 정보 등을 직접 끌어옵니다.
- 출처 그라운딩: Gemini가 검색 결과의 출처와 함께 답을 주기 때문에, 추측이나 환각 위험이 줄어듭니다.
준비물 두 가지
설치 자체는 30초면 끝나지만 다음 두 가지를 먼저 갖추셔야 합니다.
- Node.js 18 이상:
node -v로 버전 확인. 미설치라면 nodejs.org에서 LTS 받아 설치하십시오. - Gemini API 키: Google AI Studio에 구글 계정으로 로그인 → “Get API key” 메뉴에서 무료 발급. 카드 등록 없이 무료 티어부터 사용할 수 있습니다.
발급받은 키는 AIzaSy...로 시작하는 문자열입니다. 외부에 노출되지 않도록 환경변수나 설정 파일에서만 다루십시오.
설치 두 가지 방법
Gemini Search MCP의 npm 패키지는 mcp-gemini-google-search입니다. 설치는 두 가지 방식 중 편한 쪽을 고르시면 됩니다.
방법 1: claude mcp 명령으로 추가 (간단)
클로드 코드 세션 안에서 한 줄로 추가합니다. 어떤 프로젝트에서든 쓸 수 있도록 user scope로 두는 것이 일반적으로 편합니다.
claude mcp add --scope user GeminiSearch -- npx -y mcp-gemini-google-search
그 후 환경변수 GEMINI_API_KEY를 셸 또는 클로드 코드 설정에 등록해 주십시오. 셸 환경에 두실 경우는 다음과 같습니다.
export GEMINI_API_KEY="AIzaSy..."
이 한 줄을 본인의 ~/.zshrc나 ~/.bashrc에 추가해 두시면 매번 새로 띄울 때마다 자동 적용됩니다.
방법 2: .mcp.json 직접 편집 (프로젝트 공유)
팀과 공유할 프로젝트라면 저장소 루트의 .mcp.json에 직접 적어 두는 편이 깔끔합니다. 다음과 같은 형태입니다.
| 키 | 값 |
|---|---|
| command | /opt/homebrew/bin/npx (또는 본인 시스템 npx 경로) |
| args | [“-y”, “mcp-gemini-google-search”] |
| env.GEMINI_API_KEY | ${GEMINI_API_KEY} 형태 권장 |
키 값을 ${GEMINI_API_KEY}처럼 환경변수 참조로 두시면 .mcp.json이 Git에 커밋돼도 키 자체는 노출되지 않습니다. 실제 값은 본인 셸 환경이나 .env에서 주입하십시오.
설치 후 확인
설치 직후 다음 두 명령으로 정상 등록 여부를 확인하십시오.
- 등록 확인:
claude mcp list— GeminiSearch가 활성 상태로 보여야 합니다. - 도구 호출 가능 여부: 클로드 코드 세션을 새로 띄우고 “GeminiSearch로 OpenAI 최근 발표 검색해 줘”처럼 자연어로 요청. 자동완성에
mcp__GeminiSearch__google_search같은 도구가 잡히면 정상입니다.
안 보이면 세션을 한 번 완전히 재시작하시고, 여전히 문제가 있으면 claude --debug로 띄워 어떤 MCP 서버가 로드되는지 직접 확인하십시오.
실제 사용 시나리오
설치 후 클로드 코드는 검색이 필요한 순간에 자동으로 이 서버를 호출하기 시작합니다. 잘 활용되는 패턴 몇 가지를 정리하면 다음과 같습니다.
- 최신 라이브러리 정보: “Next.js 최신 버전의 Server Actions 변경점 검색해 줘” 같은 요청에서 학습 시점 이후 정보까지 가져옵니다.
- 오류 메시지 검색: 처음 보는 스택 트레이스를 그대로 던지면 같은 오류를 다룬 GitHub 이슈·블로그 글까지 그라운딩해 답합니다.
- 도큐먼트 위치 찾기: “Anthropic Claude Code의 hooks 공식 문서 URL 찾아 줘”처럼 출처 자체를 요청할 수 있습니다.
- 리서치 자료 모음: 블로그 초안, 시장 조사, 경쟁 분석처럼 여러 출처를 묶어야 하는 작업에 유용합니다.
Perplexity MCP와 무엇이 다른가
비슷한 위치의 도구로 Perplexity MCP가 자주 비교됩니다. 둘은 설계와 결제 모델이 다릅니다.
| 구분 | Gemini Search MCP | Perplexity MCP |
|---|---|---|
| 검색 엔진 | 구글 검색 + Gemini 그라운딩 | Perplexity 자체 검색 + AI 요약 |
| 무료 한도 | Google AI Studio 무료 티어 넉넉 | API 무료 한도 작은 편 |
| 응답 스타일 | 출처 링크와 함께 정리된 답 | 요약 친화적, 인용 번호 표기 |
| 장점 | 비용 부담 적고 일반 검색에 강함 | 최신·뉴스 검색 정확도 높음 |
| 단점 | 고부하 시간대 503 발생 가능 | API 한도와 결제가 빠르게 도달 |
실무에서는 둘 다 깔아 두고, 평소에는 무료 한도가 큰 Gemini Search를 1순위로 쓰다가 503이나 답이 부족할 때 Perplexity로 폴백하는 방식이 자주 쓰입니다.
안 될 때 점검 순서
“분명 깔았는데 검색이 안 된다”는 상황에서 빠르게 원인을 좁히는 방법입니다.
- 1.
claude mcp list로 GeminiSearch가 등록되어 있는지 확인 - 2. 환경변수
echo $GEMINI_API_KEY로 키가 실제 셸에 잡혀 있는지 확인 - 3. 키가 만료·오타가 아닌지 Google AI Studio에서 재확인
- 4. 클로드 코드 세션을 완전히 재시작
- 5. 503·UNAVAILABLE 에러가 반복되면 잠깐 시간을 두고 재시도(Gemini 측 일시 부하)
- 6. 회사 네트워크에서 외부 API 차단되어 있지 않은지 확인
비용은 정말 무료인가요
Google AI Studio의 무료 티어 안에서 사용하시면 추가 비용 없이 호출이 가능합니다. 일반적인 개인 개발 용도, 글 한두 편 리서치 정도는 무료 한도 안에서 충분히 처리됩니다. 다만 다음 경우는 유료 청구로 넘어갈 수 있으니 주의하십시오.
- 월간 무료 토큰·요청 한도를 초과한 경우
- Google AI Studio가 아닌 Google Cloud Vertex AI 경로로 호출하는 경우(별도 과금)
- 다른 Gemini 기능(이미지 생성·고용량 컨텍스트 등)을 같이 쓰는 경우
본인의 사용량은 Google AI Studio 사용량 페이지에서 언제든 확인하실 수 있습니다.
자주 묻는 질문
클로드만으로는 웹 검색이 정말 안 되나요?
클로드 코드 자체는 셸·파일·MCP 도구만 호출하는 구조라 직접 웹에 접근하지 않습니다. WebSearch 같은 별도 도구나 MCP 서버를 붙여야 검색이 가능해집니다. Gemini Search MCP는 그중 가장 비용 부담이 적은 선택지입니다.
한 번 깔면 모든 프로젝트에서 자동으로 동작하나요?
--scope user로 추가하셨다면 본인의 모든 프로젝트에서 동작합니다. .mcp.json에 직접 적으셨다면 그 프로젝트에서만 동작합니다.
API 키가 .mcp.json에 남아 노출이 걱정됩니다.
${GEMINI_API_KEY}처럼 환경변수 참조 형태로 두시고 실제 값은 본인 셸이나 .env에 보관하십시오. 그러면 .mcp.json이 Git에 올라가도 키는 함께 올라가지 않습니다.
Perplexity와 둘 중 하나만 깔아야 한다면 뭐가 좋을까요?
비용·범용성을 중시하시면 Gemini Search, 답변 품질·인용 정제도를 중시하시면 Perplexity가 일반적으로 더 잘 맞습니다. 결정이 어려우시면 무료 한도가 큰 Gemini Search부터 시작하시고, 부족하면 Perplexity를 추가하시는 순서를 권해 드립니다.
정리
Gemini Search MCP는 클로드 코드에 “구글 검색이라는 눈”을 달아 주는 가장 가벼운 방법입니다. 패키지는 mcp-gemini-google-search 한 개, 명령은 claude mcp add --scope user GeminiSearch -- npx -y mcp-gemini-google-search 한 줄, 키는 Google AI Studio 무료 발급 한 장이면 시작할 수 있습니다. 한 번 설치해 두시면 클로드가 알아서 검색이 필요한 순간에 호출하므로, 코드 작업 중에 자연스럽게 최신 웹 정보가 답에 섞여 들어오기 시작합니다. 비용 부담이 적은 만큼, MCP 입문용으로도 가장 추천드릴 만한 도구입니다.