de en es ja ko ru zh

grok-web-search-mcp

Name: grok-web-search-mcp
Author: NakanoSanku

by NakanoSanku

Overview Schema Related Servers Score Discussions

Python

Remote

言語: 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 検索	デフォルトで含まれる。`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 を使用してください。

使用技術

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 を設定します（設定を参照）。

設定

変数	必須	デフォルト	説明
`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トランスポートのドキュメント/例
検索品質のためのゴールデンセット評価ハーネス

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

コントリビューション

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

プロジェクトをフォークします
フィーチャーブランチを作成します（git checkout -b feature/AmazingFeature）
変更をコミットします（git commit -m 'Add some AmazingFeature'）
ブランチにプッシュします（git push origin feature/AmazingFeature）
プルリクエストを開きます

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

ライセンス

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

謝辞

Available Tools

1 tool

web_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.

ParametersJSON Schema

Name	Required	Description
`model`	No	Optional model override (default from GROK_MODEL / grok-4.5).
`query`	Yes	Natural-language search question or topic.
`images`	No	Optional image input(s) for visual questions: URL / data-URI / local path (comma or newline separated, max 5). Not an image-search API.
`to_date`	No	Optional inclusive X search end date (YYYY-MM-DD).
`from_date`	No	Optional inclusive X search start date (YYYY-MM-DD).
`image_detail`	No	Vision detail for input images: low \| high \| auto (default high).
`system_prompt`	No	Optional system instruction prepended to the request.
`allowed_domains`	No	Optional comma-separated allowlist (max 5). Mutually exclusive with excluded_domains.
`excluded_domains`	No	Optional comma-separated denylist (max 5).
`reasoning_effort`	No	Optional thinking length for reasoning models: low \| medium \| high.
`allowed_x_handles`	No	Optional comma-separated X handle allowlist (max 20). Mutually exclusive with excluded_x_handles.
`excluded_x_handles`	No	Optional comma-separated X handle denylist (max 20).
`enable_image_understanding`	No	Analyze images found on browsed pages and X posts (default on).
`enable_video_understanding`	No	Analyze videos found in X posts (default off).

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses return format, image handling constraints (max 5, types), and scoping of image/video understanding. It lacks explicit mention of read-only nature but is otherwise transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (6 sentences), front-loaded with core purpose, and every sentence adds meaningful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (14 parameters, optional features) and the presence of an output schema, the description covers most behavioral aspects. Minor gaps exist (e.g., rate limits, indexing scope), but overall it is thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by summarizing key parameters (domain filters, reasoning_effort) and clarifying behavior of image/video understanding fields, which are not detailed in schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs 'Live web and X search via Grok' and details return values. It uses a specific verb (search) and resource (web and X), and the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While no sibling tools exist for comparison, the description provides clear context on features and filters, sufficiently guiding usage. It could benefit from explicit when-not-to-use, but the absence of alternatives makes this less critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

1 tool updatev0.1.0Jul 28, 2026
- First observedweb_search

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0

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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

pixserp A
com.pixserp
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Search Browser Automation
12
Keenable Web Search A
ai.keenable.api
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.
Research & Data Search Web Scraping
23
mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
MESSORA A
dev.messora
Scrape, crawl and search the web for AI agents via MCP.
Web Scraping Browser Automation Search
51

Related MCP Servers

xai-search-mcp
Search Social Media
kicito
A
license
A
quality
D
maintenance
An MCP server that provides real-time web search and X (Twitter) search capabilities via the xAI API.
Updated 5 months ago (2026-04-22 12:57 UTC)
2
28
MIT
WebQuest MCP
Browser Automation Web Scraping
mustafametesengul
A
license
Not graded
quality
C
maintenance
A Model Context Protocol server that exposes powerful web search and scraping tools to AI agents and MCP-compatible clients.
Updated 7 months ago (2026-02-12 20:56 UTC)
Apache 2.0
bluex-mcp
Search Social Media
Derek-Wong213
A
license
A
quality
B
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.
Updated 2 months ago (2026-06-30 16:31 UTC)
3
1
MIT
grok-mcp
Search Web Scraping Social Media
dq52099
F
license
Not graded
quality
C
maintenance
MCP server providing web search, news search, and X/Twitter search capabilities via HTTP or stdio.
Updated a month ago (2026-07-26 22:44 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NakanoSanku/grok-web-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

プロジェクトについて

特徴

使用技術

はじめに

前提条件

クイックスタート（GitHub からの uvx）

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

設定

使い方

サーバーの起動

MCP ホスト設定

ツール: web_search

レスポンスの形式

Pythonクライアントの例

開発

ロードマップ

コントリビューション

ライセンス

謝辞

Available Tools

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

xai-search-mcp

WebQuest MCP

bluex-mcp

grok-mcp

Latest Blog Posts

MCP directory API

ツール: `web_search`