grok-search

English | 简体中文

Grok-with-Tavily MCP，为 Claude Code 提供更完善的网络访问能力

Это форк (sunami-grok-search) проекта GuDaStudio/GrokSearch. В исходной версии web_search передаёт поиск внешнему шлюзу, и при прямом подключении к официальному api.x.ai реального поиска не происходит — модель лишь выдумывает ссылки citation_card, а sources_count всегда равен 0. Этот форк использует нативные инструменты web_search / x_search из xAI Responses API, ссылки читаются структурно из annotations[].url_citation, а фильтры по аккаунтам/времени для поиска X вынесены в параметры. Подробности изменений — в SUNAMI.md; при развёртывании на новой машине просто передайте промпт из PROMPT.md агенту. Ниже — оригинальная документация вышестоящего проекта.

一、概述

Grok Search MCP — это MCP-сервер на базе FastMCP с двухдвижковой архитектурой: Grok отвечает за AI-управляемый интеллектуальный поиск, а Tavily — за высокоточное извлечение веб-страниц и карту сайтов. Каждый движок используется по своему назначению, обеспечивая LLM-клиентам вроде Claude Code / Cherry Studio полноценный доступ к сети в реальном времени.

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

• Автоматическая подстановка времени (определяет запросы, связанные со временем, и подставляет локальный временной контекст)

• Отключение официальных WebSearch/WebFetch в Claude Code одним кликом, принудительная маршрутизация на этот инструмент

• Умные повторы (поддержка разбора заголовка Retry-After + экспоненциальная задержка)

• Мониторинг родительского процесса (на Windows автоматически определяет выход родительского процесса, предотвращая появление процессов-зомби)

Демонстрация результатов

В качестве примера возьмём настройку этого MCP в cherry studio: показано, как модель claude-opus-4.6 с помощью этого проекта собирает внешние знания и снижает уровень галлюцинаций. Как показано на рисунке выше, для честного эксперимента мы включили встроенный поисковый инструмент модели Claude, однако opus 4.6 по-прежнему полагается на свои внутренние знания и не обращается к официальной документации FastAPI за актуальными примерами. Как показано на рисунке выше, при включённом grok-search MCP в тех же экспериментальных условиях opus 4.6 активно выполняет несколько поисков, чтобы получить официальную документацию и дать более надёжные ответы.

二、安装

Предварительные требования

• 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

Можно добавить параметр --native-tls в аргументы uvx, чтобы использовать системное хранилище сертификатов:

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

Инструмент автоматически изменит permissions.deny в проектном файле .claude/settings.json, отключив официальные WebSearch и WebFetch в Claude Code одним кликом, что заставит claude code использовать этот проект для поиска!

三、Описание MCP-инструментов

web_search — AI-поиск в сети

Выполняет AI-управляемый поиск в сети через Grok API. По умолчанию возвращает только основной текст ответа Grok, а также возвращает session_id для последующего получения источников.

Вывод web_search не раскрывает источники, возвращается только sources_count; источники кэшируются на сервере по session_id, их можно получить через get_sources.

Автоматически определяет в запросе ключевые слова, связанные со временем (например, «最新», «今天», «recent» и т. д.), и подставляет локальный временной контекст для повышения точности поиска актуальной информации.

Возвращаемое значение (структурированный словарь):

• session_id: ID сессии данного запроса

• content: основной текст ответа Grok (источники автоматически удалены)

• sources_count: количество закэшированных источников

get_sources — получение источников

Получает все источники соответствующего web_search по session_id.

Возвращаемое значение (структурированный словарь):

• 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 — управление маршрутизацией инструментов

Изменяет permissions.deny в проектном файле .claude/settings.json, отключая официальные WebSearch и WebFetch в Claude Code одним кликом.

search_planning — планирование поиска

Структурированный каркас планирования поиска (поэтапный, многораундовый), используется для генерации выполнимого плана поиска перед выполнением сложного поиска.

四、Часто задаваемые вопросы

Лицензия

MIT License

Если этот проект оказался вам полезен, поставьте Star!