grok-web-search-mcp
言語: English | 中文
プロジェクトについて
エージェントには、チャット補完だけでなく、引用付きのライブな 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 検索 | デフォルトで含まれる。 |
X フィルター | 許可/拒否リスト(最大 20 件、 |
ドメインフィルター | 許可リスト または 拒否リスト(最大 5 件、排他的。スキーム/パスは除去) |
検索メディア理解 | Web ページと X 投稿の画像、X 投稿の動画 |
クライアント画像入力 | オプションの |
軽量な JSON 出力 | ツール結果に |
プロトコルエラー | アップストリーム/検証の失敗は MCP の |
リトライ | 429 / 502 / 503 / 504 とトランスポートタイムアウトをバックオフ付きでリトライ |
プロキシ対応 |
|
GitHub インストール |
|
含まれないもの: enable_image_search(Web 画像ギャラリーの埋め込み)。自分で 画像を提供する場合は images を使用し、閲覧したページや X 投稿の画像には enable_image_understanding を使用してください。
使用技術
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ローカル開発環境のインストール
リポジトリをクローン:
git clone https://github.com/NakanoSanku/grok-web-search-mcp.git cd grok-web-search-mcp依存関係をインストール:
uv sync # or: pip install -e ".[dev]"ローカルの env ファイルを作成:
cp .env.example .env.envを編集し、少なくともGROK_API_KEYを設定します(設定 を参照)。
設定
変数 | 必須 | デフォルト | 説明 |
| はい | — |
|
| いいえ |
|
|
| いいえ |
|
|
| いいえ |
| リクエストタイムアウト(秒、1〜3600)。高い推論 + 検索には数分かかることがあります |
| いいえ |
| TCP/TLS 接続タイムアウト( |
| いいえ |
| 閲覧したページと X 投稿の画像を分析 |
| いいえ |
| デフォルトの思考量: |
| いいえ |
|
|
| いいえ | cwd | 有効時のローカル画像のディレクトリ制限 |
| いいえ |
| 429/5xx/タイムアウトのリトライ回数(0〜8) |
| いいえ |
|
|
| いいえ |
| X 投稿の動画を分析(オペレーター専用。ツール引数ではない) |
| いいえ | — | オペレーター用 Web 許可リスト(最大 5 件)。呼び出し側は設定不可 |
| いいえ | — | オペレーター用 Web 拒否リスト(最大 5 件) |
| いいえ | — | オペレーター用 X ハンドル許可リスト(最大 20 件) |
| いいえ | — | オペレーター用 X ハンドル拒否リスト(最大 20 件) |
| いいえ | — | サーバーが管理するシステムプロンプトに追記される追加ルール |
シークレットは 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-mcpMCP ホスト設定
推奨: 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、ドメイン/ハンドルフィルター)は 拒否されます。品質調整は環境変数にあり、モデル間で検索動作がずれないようにしています。
パラメータ | 型 | 説明 |
| string | 必須。 自然言語の質問。2〜600 文字。キーワードリスト( |
|
| デフォルトは |
|
| デフォルトは |
| 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_searchMCPツールデフォルトでアップストリームの
web_searchとx_searchを有効化Xハンドル/日付フィルターと画像/動画の理解
カスタム
base_url/ プロキシサポートドメインの許可/拒否フィルター
オプションのマルチモーダル画像入力
uvxによるGitHubからのインストール/実行プロトコルレベルのエラー、リトライ、タイムアウト/推論のデフォルト値
ローカル画像ジェイル(デフォルトで無効)
標準的なMCP呼び出し契約(
query/scope/recency/images)オプションのStreamable HTTPトランスポートのドキュメント/例
検索品質のためのゴールデンセット評価ハーネス
オープンイシューを参照してください。
コントリビューション
コントリビューションを歓迎します。
プロジェクトをフォークします
フィーチャーブランチを作成します(
git checkout -b feature/AmazingFeature)変更をコミットします(
git commit -m 'Add some AmazingFeature')ブランチにプッシュします(
git push origin feature/AmazingFeature)プルリクエストを開きます
ツールのインターフェースを簡潔に保ってください:多数の薄いラッパーよりも、十分にドキュメント化された1つのツールを優先してください。
ライセンス
MITライセンスの下で配布されています。詳細はLICENSEを参照してください。
謝辞
Available Tools
1 toolweb_searchA
Live web and X search via Grok. Returns ok, text (answer), citations (URL list). Optional images: public URL, data:image/...;base64,..., or local file path (max 5) to ask about a picture while searching. Supports web domain filters, X handle/date filters, and reasoning_effort (low/medium/high). Image understanding applies to browsed pages and X posts; video understanding applies to X posts only.
Inputs: query (required), model, images, to_date, +10 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no possibility of confusion or overlap with other tools.
With a single tool, naming consistency is inherently perfect as there is no pattern to break.
A single tool is slightly minimal but reasonably scoped for a focused web search server, as the tool itself is comprehensive.
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
Related MCP Connectors
Web search API and MCP server for developers building AI agents.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Search, read, and act on the web. The Stophy MCP server for agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that provides real-time web search and X (Twitter) search capabilities via the xAI API.239 npmMIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that exposes powerful web search and scraping tools to AI agents and MCP-compatible clients.Apache 2.0
- AlicenseAqualityCmaintenanceMCP 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.31MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.-