Skip to main content
Glama
grok-web-search-mcp

grok-web-search-mcp

by NakanoSanku

言語: English | 中文

Python License: MIT MCP xAI GitHub

プロジェクトについて

エージェントには、チャット補完だけでなく、引用付きのライブな Web および X へのアクセスが必要です。このプロジェクトは、xAI のサーバーサイドツールである web_search と x_search を 単一の MCP ツール としてラップし、Grok、Cursor、Claude Desktop などのホストが xAI クライアントロジックを組み込むことなく呼び出せるようにします。

リポジトリ: https://github.com/NakanoSanku/grok-web-search-mcp

アップストリーム呼び出し(簡略化):

POST {base_url}/responses
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "model": "grok-4.5",
  "input": [{"role": "user", "content": "<query>"}],
  "tools": [
    {"type": "web_search", "enable_image_understanding": true},
    {
      "type": "x_search",
      "allowed_x_handles": ["xai"],
      "from_date": "2025-10-01",
      "to_date": "2025-10-10",
      "enable_image_understanding": true,
      "enable_video_understanding": true
    }
  ]
}

設計目標:

  • 1 つの MCP ツール、1 つの呼び出し契約 — モデルが渡せるのは query / scope / recency / images のみ

  • 軽量な結果 — query / text / citations / sources_used(アップストリームの生データは含めない)

  • カスタム base URL — 公式の https://api.x.ai/v1 または OpenAI 互換プロキシ

  • オプションのビジョン入力 — https URL またはデータ URI を添付可能(ローカルパスはオプトイン)

  • PyPI 不要 — uvx --from git+... で GitHub から直接実行

特徴

機能

備考

ライブ Web 検索

Grok がソース URL 付きの回答を生成

ライブ X 検索

デフォルトで含まれる。scope="web" または scope="x" で制限可能

X フィルター

許可/拒否リスト(最大 20 件、@ は除去)と両端を含む日付範囲を処理

ドメインフィルター

許可リスト または 拒否リスト(最大 5 件、排他的。スキーム/パスは除去)

検索メディア理解

Web ページと X 投稿の画像、X 投稿の動画

クライアント画像入力

オプションの images(https / データ URI。ローカルパスはオプトイン)

軽量な JSON 出力

ツール結果に model / base_url / 注釈 / 生ペイロードを含めない

プロトコルエラー

アップストリーム/検証の失敗は MCP の isError を設定(偽の ok: false ペイロードではない)

リトライ

429 / 502 / 503 / 504 とトランスポートタイムアウトをバックオフ付きでリトライ

プロキシ対応

GROK_BASE_URL / XAI_BASE_URL

GitHub インストール

uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git

含まれないもの: enable_image_search(Web 画像ギャラリーの埋め込み)。自分で 画像を提供する場合は images を使用し、閲覧したページや X 投稿の画像には enable_image_understanding を使用してください。

使用技術

  • Python

  • FastMCP

  • httpx

  • xAI API

  • MCP

  • uv

Related MCP server: WebQuest MCP

はじめに

前提条件

  • Python 3.10+

  • xAI API キー(互換ゲートウェイのキーでも可)

  • uv(GitHub からの uvx に推奨)

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

クイックスタート(GitHub からの uvx)

日常的な MCP 利用にはローカルクローンは不要です:

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

再現性が必要な場合は、ブランチ、タグ、またはコミットを固定してください:

uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main grok-web-search-mcp
# uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git@v0.3.0 grok-web-search-mcp

ローカル開発環境のインストール

  1. リポジトリをクローン:

    git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
    cd grok-web-search-mcp
  2. 依存関係をインストール:

    uv sync
    # or: pip install -e ".[dev]"
  3. ローカルの env ファイルを作成:

    cp .env.example .env
  4. .env を編集し、少なくとも GROK_API_KEY を設定します(設定 を参照)。

設定

変数

必須

デフォルト

説明

GROK_API_KEY

はい

—

XAI_API_KEY / GROK_WEB_SEARCH_API_KEY も受け付けます

GROK_BASE_URL

いいえ

https://api.x.ai/v1

XAI_BASE_URL / GROK_WEB_SEARCH_BASE_URL も可

GROK_MODEL

いいえ

grok-4.5

XAI_MODEL も可

GROK_TIMEOUT

いいえ

300

リクエストタイムアウト(秒、1〜3600)。高い推論 + 検索には数分かかることがあります

GROK_CONNECT_TIMEOUT

いいえ

15

TCP/TLS 接続タイムアウト(GROK_TIMEOUT で上限)

GROK_ENABLE_IMAGE_UNDERSTANDING

いいえ

true

閲覧したページと X 投稿の画像を分析

GROK_REASONING_EFFORT

いいえ

low

デフォルトの思考量: low / medium / high。XAI_REASONING_EFFORT も可

GROK_ALLOW_LOCAL_IMAGES

いいえ

false

images がローカルファイルを読み取ることを許可(cwd / GROK_LOCAL_IMAGE_ROOT に制限)

GROK_LOCAL_IMAGE_ROOT

いいえ

cwd

有効時のローカル画像のディレクトリ制限

GROK_MAX_RETRIES

いいえ

3

429/5xx/タイムアウトのリトライ回数(0〜8)

GROK_LOG_LEVEL

いいえ

INFO

DEBUG / INFO / WARNING / ERROR

GROK_ENABLE_VIDEO_UNDERSTANDING

いいえ

false

X 投稿の動画を分析(オペレーター専用。ツール引数ではない)

GROK_ALLOWED_DOMAINS

いいえ

—

オペレーター用 Web 許可リスト(最大 5 件)。呼び出し側は設定不可

GROK_EXCLUDED_DOMAINS

いいえ

—

オペレーター用 Web 拒否リスト(最大 5 件)

GROK_ALLOWED_X_HANDLES

いいえ

—

オペレーター用 X ハンドル許可リスト(最大 20 件)

GROK_EXCLUDED_X_HANDLES

いいえ

—

オペレーター用 X ハンドル拒否リスト(最大 20 件)

GROK_SEARCH_INSTRUCTIONS

いいえ

—

サーバーが管理するシステムプロンプトに追記される追加ルール

シークレットは git にコミットしないでください。可能であれば、MCP 設定にはホストが注入する環境変数を使用してください。

使い方

サーバーの起動

推奨(GitHub から):

export GROK_API_KEY=xai-...
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

ローカルチェックアウトから:

export GROK_API_KEY=xai-...
# Windows PowerShell: $env:GROK_API_KEY="xai-..."

uv run grok-web-search-mcp
# or
uv run python -m grok_web_search_mcp

互換プロキシの例:

export GROK_API_KEY=sk-xxx
export GROK_BASE_URL=http://127.0.0.1:8317/v1
export GROK_MODEL=grok-4.5
uvx --from git+https://github.com/NakanoSanku/grok-web-search-mcp.git grok-web-search-mcp

MCP ホスト設定

推奨: GitHub から uvx で実行(ローカルパス不要)。

JSON 形式のホスト(Cursor / Claude Desktop など):

{
  "mcpServers": {
    "grok-web-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
        "grok-web-search-mcp"
      ],
      "env": {
        "GROK_API_KEY": "xai-your-key",
        "GROK_BASE_URL": "https://api.x.ai/v1",
        "GROK_MODEL": "grok-4.5"
      }
    }
  }
}

Grok ユーザー設定(~/.grok/config.toml):

[mcp_servers.grok-web-search]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git",
  "grok-web-search-mcp",
]
enabled = true

[mcp_servers.grok-web-search.env]
GROK_API_KEY = "xai-your-key"
GROK_BASE_URL = "https://api.x.ai/v1"
GROK_MODEL = "grok-4.5"

ref を固定(ブランチ / タグ / コミット):

args = [
  "--from",
  "git+https://github.com/NakanoSanku/grok-web-search-mcp.git@main",
  "grok-web-search-mcp",
]

ローカル開発のみ(チェックアウトへの絶対パス):

[mcp_servers.grok-web-search]
command = "uv"
args = [
  "run",
  "--directory",
  "/absolute/path/to/grok-web-search-mcp",
  "grok-web-search-mcp",
]
enabled = true

ツール: web_search

すべてのホストモデルは同じ 4 キーの契約を使用する必要があります。追加の引数(model、reasoning_effort、system_prompt、ドメイン/ハンドルフィルター)は 拒否されます。品質調整は環境変数にあり、モデル間で検索動作がずれないようにしています。

パラメータ

型

説明

query

string

必須。 自然言語の質問。2〜600 文字。キーワードリスト(xAI Grok valuation)やチャット履歴ではありません。キーワードの羅列はサーバー側で書き換えられます。

scope

"all" | "web" | "x"

デフォルトは all(Web + X)。一般的な事実には web、投稿/アカウントのみには x を使用。

recency

"any" | "day" | "week" | "month" | "year"

デフォルトは any。ユーザーが期間を指定した場合のみ設定。

images

string[]?

オプションの画像 URL(http(s) / データ URI、最大 5 件)。ユーザーが画像を提供した場合のみ。

標準的な例:

{ "query": "What is xAI's latest valuation?" }

サーバーはその後、query を正規化し、固定のシステムプロンプトを注入し、env からオペレーターフィルターを適用し、recency を X の日付範囲にマッピングし、常に設定済みのモデル / 推論量を使用します。

images は Responses API の input_image パーツです。ローカルファイルシステムのパスは デフォルトで無効 です。これは「Web でストック画像を検索する」機能では ありません。

レスポンスの形式

成功(MCP isError: false、構造化コンテンツ):

{
  "query": "What is xAI?",
  "text": "...",
  "citations": [{"url": "https://x.ai", "title": "xAI"}],
  "sources_used": ["web", "x"],
  "scope": "all",
  "recency": "any"
}

失敗は、短いメッセージを伴うプロトコルレベルのツールエラー(isError: true)です。例:Grok API error (401): Invalid API key。不完全または空のアップストリームレスポンスもエラーであり、暗黙の成功ではありません。

意図的に返されないもの:APIキー、model、base_url、生のアップストリームJSON、アノテーションブロブ(URLはcitationsにのみ抽出されます)。設定の診断はツール結果の外部(env / ホストMCP設定 / stderrログ)で行います。

Pythonクライアントの例

import asyncio
from grok_web_search_mcp.client import GrokWebSearchClient
from grok_web_search_mcp.config import Settings

async def main():
    async with GrokWebSearchClient(Settings.from_env()) as client:
        result = await client.web_search("What is xAI?")
        print(result.to_dict())

asyncio.run(main())

実際の呼び出しはモデルとサーバー側の検索クォータを消費します。ユニットテストはモックを使用し、ネットワークにアクセスしません。

開発

git clone https://github.com/NakanoSanku/grok-web-search-mcp.git
cd grok-web-search-mcp
uv sync --extra dev
uv run pytest
# live API (optional): GROK_LIVE=1 uv run pytest -m live

プロジェクト構成:

src/grok_web_search_mcp/
  server.py    # MCP tool surface
  client.py    # Responses API client + image helpers
  config.py    # Environment settings
tests/

ロードマップ

  • 単一の軽量なweb_search MCPツール

  • デフォルトでアップストリームのweb_searchとx_searchを有効化

  • Xハンドル/日付フィルターと画像/動画の理解

  • カスタムbase_url / プロキシサポート

  • ドメインの許可/拒否フィルター

  • オプションのマルチモーダル画像入力

  • uvxによるGitHubからのインストール/実行

  • プロトコルレベルのエラー、リトライ、タイムアウト/推論のデフォルト値

  • ローカル画像ジェイル(デフォルトで無効)

  • 標準的なMCP呼び出し契約(query / scope / recency / images)

  • オプションのStreamable HTTPトランスポートのドキュメント/例

  • 検索品質のためのゴールデンセット評価ハーネス

オープンイシューを参照してください。

コントリビューション

コントリビューションを歓迎します。

  1. プロジェクトをフォークします

  2. フィーチャーブランチを作成します(git checkout -b feature/AmazingFeature)

  3. 変更をコミットします(git commit -m 'Add some AmazingFeature')

  4. ブランチにプッシュします(git push origin feature/AmazingFeature)

  5. プルリクエストを開きます

ツールのインターフェースを簡潔に保ってください:多数の薄いラッパーよりも、十分にドキュメント化された1つのツールを優先してください。

ライセンス

MITライセンスの下で配布されています。詳細はLICENSEを参照してください。

謝辞

Available Tools

1 tool

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusion or overlap with other tools.

    Naming Consistency5/5

    With a single tool, naming consistency is inherently perfect as there is no pattern to break.

    Tool Count4/5

    A single tool is slightly minimal but reasonably scoped for a focused web search server, as the tool itself is comprehensive.

    Completeness5/5

    The tool covers web search, X search, image understanding, domain and date filters, and reasoning effort, leaving no obvious gaps for its stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that provides real-time web search and X (Twitter) search capabilities via the xAI API.
      2
      39 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for live X/Twitter and web search, driven by your locally logged-in Grok CLI and leveraging your X Premium or SuperGrok subscription quota.
      3
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.
      -