grok-search

English | 简体中文

Grok-with-Tavily MCP、Claude Code により充実したネットワークアクセス機能を提供

これは GuDaStudio/GrokSearch のフォーク（sunami-grok-search）です。 上流の web_search は検索を上流ゲートウェイに委託しており、公式の api.x.ai に直接接続しても実際には検索されず、 モデルが citation_card の引用を捏造し、sources_count が常に 0 になるだけです。 本フォークは xAI Responses API のネイティブな web_search / x_search ツールを利用するように変更し、 引用は annotations[].url_citation から構造化して読み取り、X 検索のアカウント/時間フィルタをパラメータとして公開しています。 変更の詳細は SUNAMI.md を参照してください。別マシンにデプロイする場合は PROMPT.md のプロンプトを agent に渡すだけです。以下は上流の元のドキュメントです。

一、概要

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 は自発的に複数回の検索を呼び出し、公式ドキュメントを取得して、より信頼性の高い回答を提供します。

二、インストール

前提条件

• 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 に本プロジェクトを呼び出して検索を実行させます！

三、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 — 検索プランニング

構造化された検索プランニングのスキャフォールド（段階的、複数ラウンド）。複雑な検索を実行する前に、実行可能な検索プランを生成するために使用します。

四、よくある質問

ライセンス

MIT License

このプロジェクトが役に立ったなら、Star をお願いします！