grok-search

English | 简体中文

Grok-with-Tavily MCP, Claude Code에 더 완벽한 네트워크 접근 기능 제공

이것은 GuDaStudio/GrokSearch의 fork(sunami-grok-search)입니다. 업스트림의 web_search는 검색을 업스트림 게이트웨이에 위임하므로, 공식 api.x.ai에 직접 연결하면 실제 검색이 수행되지 않고 모델이 citation_card 인용을 지어내고 sources_count가 항상 0이 됩니다. 이 fork는 xAI Responses API의 네이티브 web_search / x_search 도구를 사용하도록 변경했으며, 인용은 annotations[].url_citation에서 구조적으로 읽어오고, X 검색의 계정/시간 필터를 파라미터로 개방했습니다. 변경 사항에 대한 자세한 내용은 **SUNAMI.md**를 참조하세요. 다른 머신에 배포할 때는 **PROMPT.md**의 프롬프트를 agent에 전달하면 됩니다. 아래는 업스트림 원본 문서입니다.

1. 개요

Grok Search MCP는 FastMCP 기반으로 구축된 MCP 서버로, 이중 엔진 아키텍처를 채택합니다: Grok는 AI 기반 스마트 검색을 담당하고, Tavily는 고충실도 웹 크롤링과 사이트 매핑을 담당하여, 각각의 장점을 활용해 Claude Code / Cherry Studio 등 LLM Client에 완전한 실시간 네트워크 접근 기능을 제공합니다.

Claude ──MCP──► Grok Search Server
                  ├─ web_search  ───► Grok API（AI 搜索）
                  ├─ web_fetch   ───► Tavily Extract → Firecrawl Scrape（内容抓取，自动降级）
                  └─ web_map     ───► Tavily Map（站点映射）

기능 특징

• 이중 엔진: Grok 검색 + Tavily 크롤링/매핑, 상호 보완 협력

• Firecrawl 폴백: Tavily 추출 실패 시 자동으로 Firecrawl Scrape로 다운그레이드, 빈 콘텐츠 자동 재시도 지원

• OpenAI 호환 인터페이스, 모든 Grok 미러 사이트 지원

• 자동 시간 주입(시간 관련 쿼리 감지, 로컬 시간 컨텍스트 주입)

• Claude Code 공식 WebSearch/WebFetch를 원클릭 비활성화, 본 도구로 강제 라우팅

• 스마트 재시도(Retry-After 헤더 파싱 + 지수 백오프 지원)

• 부모 프로세스 모니터링(Windows에서 부모 프로세스 종료 자동 감지, 좀비 프로세스 방지)

효과 시연

cherry studio에서 본 MCP를 구성한 예시를 통해, claude-opus-4.6 모델이 본 프로젝트를 통해 외부 지식 수집을 구현하고 환각률을 낮추는 방법을 보여줍니다. 위 그림과 같이, 공정한 실험을 위해 claude 모델 내장 검색 도구를 켰지만, opus 4.6은 여전히 내부 상식만 믿고 FastAPI 공식 문서를 조회하여 최신 예제를 얻지 않습니다. 위 그림과 같이, grok-search MCP를 켜면 동일한 실험 조건에서 opus 4.6이 여러 번 검색을 적극적으로 호출하여 공식 문서를 확보하고 더 신뢰할 수 있는 답변을 제공합니다.

2. 설치

사전 요구 사항

• Python 3.10+

• uv(권장 Python 패키지 관리자)

• Claude Code

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Windows 사용자는 WSL에서 본 프로젝트를 실행할 것을 강력히 권장합니다.

원클릭 설치

이전에 본 프로젝트를 설치한 적이 있다면 다음 명령으로 이전 버전 MCP를 제거하세요.

claude mcp remove grok-search

다음 명령의 환경 변수를 자신의 값으로 교체한 후 실행하세요. Grok 인터페이스는 OpenAI 호환 형식이어야 합니다. Tavily는 선택 구성이며, 미구성 시 web_fetch 및 web_map 도구를 사용할 수 없습니다.

GuDa 사용자(권장)

GuDa 사용자는 GUDA_API_KEY만 구성하면 전체 서비스를 이용할 수 있으며, 모든 API 주소가 자동으로 파생됩니다:

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
    "grok-search"
  ],
  "env": {
    "GUDA_API_KEY": "your-guda-api-key"
  }
}'

사용자 정의 구성

자체 API 엔드포인트를 사용하려면 각 서비스를 개별적으로 구성할 수 있습니다:

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "TAVILY_API_KEY": "tvly-your-tavily-key",
    "TAVILY_API_URL": "https://api.tavily.com"
  }
}'

일부 기업 네트워크 또는 프록시 환경에서는 다음과 유사한 오류가 발생할 수 있습니다:

certificate verify failed self signed certificate in certificate chain

uvx 인수에 --native-tls를 추가하여 시스템 인증서 저장소를 사용하도록 할 수 있습니다:

claude mcp add-json grok-search --scope user '{ "type": "stdio", "command": "uvx", "args": [ "--native-tls", "--from", "git+https://github.com/GuDaStudio/GrokSearch@grok-with-tavily", "grok-search" ], "env": { "GUDA_API_KEY": "your-guda-api-key" } }'

그 외에도 env 필드에 더 많은 환경 변수를 구성할 수 있습니다

참고: GUDA_API_KEY를 구성하면 GROK_API_URL/GROK_API_KEY/TAVILY_*/FIRECRAWL_*는 모두 선택 사항이며, 시스템이 GUDA_BASE_URL에서 자동으로 파생합니다. 명시적으로 설정한 개별 변수의 우선순위가 더 높습니다.

설치 검증

claude mcp list

🍟 연결 성공이 표시되면, Claude 대화에 다음을 입력할 것을 적극 권장합니다

调用 grok-search toggle_builtin_tools，关闭Claude Code's built-in WebSearch and WebFetch tools

도구가 자동으로 프로젝트 수준 .claude/settings.json의 permissions.deny를 수정하여 Claude Code 공식 WebSearch와 WebFetch를 원클릭 비활성화하고, claude code가 본 프로젝트를 호출하여 검색을 수행하도록 강제합니다!

3. MCP 도구 소개

web_search — AI 웹 검색

Grok API를 통해 AI 기반 웹 검색을 실행하며, 기본적으로 Grok의 답변 본문만 반환하고, 이후 출처를 가져오기 위한 session_id를 반환합니다.

web_search 출력은 출처를 펼치지 않고 sources_count만 반환합니다. 출처는 session_id별로 서버에 캐시되며, get_sources로 가져올 수 있습니다.

쿼리에서 시간 관련 키워드(예: "최신", "오늘", "recent" 등)를 자동 감지하여 로컬 시간 컨텍스트를 주입하고, 시의성 검색의 정확도를 높입니다.

반환 값(구조화된 딕셔너리):

• session_id: 이번 쿼리의 세션 ID

• content: Grok 답변 본문(출처 자동 제거됨)

• sources_count: 캐시된 출처 수

get_sources — 출처 가져오기

session_id를 통해 해당 web_search의 모든 출처를 가져옵니다.

반환 값(구조화된 딕셔너리):

• session_id

• sources_count

• sources: 출처 목록(각 항목에 url 포함, title/description/provider 포함 가능)

web_fetch — 웹 콘텐츠 크롤링

Tavily Extract API를 통해 전체 웹 콘텐츠를 가져와 Markdown 형식으로 반환합니다. Tavily 실패 시 Firecrawl Scrape로 자동 다운그레이드하여 폴백 크롤링을 수행합니다.

web_map — 사이트 구조 매핑

Tavily Map API를 통해 웹사이트 구조를 탐색하고, URL을 발견하여 사이트맵을 생성합니다.

get_config_info — 구성 진단

매개변수 불필요. 모든 구성 상태를 표시하고, Grok API 연결을 테스트하며, 응답 시간과 사용 가능한 모델 목록을 반환합니다(API 키 자동 마스킹).

switch_model — 모델 전환

전환 후 구성은 ~/.config/grok-search/config.json에 영구 저장되어 세션 간 유지됩니다.

toggle_builtin_tools — 도구 라우팅 제어

프로젝트 수준 .claude/settings.json의 permissions.deny를 수정하여 Claude Code 공식 WebSearch와 WebFetch를 원클릭 비활성화합니다.

search_planning — 검색 계획

구조화된 검색 계획 스캐폴드(단계별, 다중 라운드)로, 복잡한 검색을 실행하기 전에 실행 가능한 검색 계획을 먼저 생성하는 데 사용됩니다.

4. 자주 묻는 질문

라이선스

MIT License

이 프로젝트가 도움이 되셨다면 Star를 눌러주세요!