de en es ja ko ru zh

grok-web-search-mcp

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

by NakanoSanku

Overview Schema Source Related Servers Score Discussions

Python

Remote

语言： 英文 | 中文

关于项目

智能体需要带引用的实时网页和 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
    }
  ]
}

设计目标：

一个 MCP 工具，一个调用契约 — 模型只能传递 query / scope / recency / images
精简结果 — query / text / citations / sources_used（无原始上游转储）
自定义基础 URL — 官方 https://api.x.ai/v1 或 OpenAI 兼容代理
可选视觉输入 — 附加 https URL 或 data URI（本地路径为可选）
无需 PyPI — 直接通过 uvx --from git+... 从 GitHub 运行

特性

能力	说明
实时网页搜索	Grok 综合答案并附上来源 URL
实时 X 搜索	默认包含；设置 `scope="web"` 或 `scope="x"` 以限制
X 过滤器	处理允许/拒绝列表（最多 20 个，`@` 会被去除）和包含日期范围
域名过滤器	允许列表或拒绝列表（最多 5 个，互斥；去除 scheme/path）
搜索媒体理解	网页和 X 帖子上的图片；X 帖子上的视频
客户端图片输入	可选 `images`（https / data 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（网页图片库嵌入）。当你提供图片时使用 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]"
```
创建本地环境文件：
```
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`	否	—	操作员网页允许列表（最多 5 个）。调用者不能设置此选项
`GROK_EXCLUDED_DOMAINS`	否	—	操作员网页拒绝列表（最多 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 主机配置

首选：使用 uvx 从 GitHub 运行（无需本地路径）。

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"

固定引用（分支 / 标签 / 提交）：

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`

每个主机模型必须使用相同的四键契约。额外参数（model、reasoning_effort、system_prompt、域名/句柄过滤器）会被拒绝。质量旋钮位于环境变量中，因此搜索行为不会在模型之间漂移。

参数	类型	说明
`query`	string	必需。自然语言问题，2–600 个字符。不是关键词列表（`xAI Grok valuation`），也不是聊天历史。关键词包会在服务端重写。
`scope`	`"all"` \| `"web"` \| `"x"`	默认 `all`（网页 + X）。一般事实使用 `web`；仅帖子/账号使用 `x`。
`recency`	`"any"` \| `"day"` \| `"week"` \| `"month"` \| `"year"`	默认 `any`。仅当用户要求时间窗口时设置。
`images`	string[]?	可选的图片 URL（http(s) / data URI，最多 5 个）。仅当用户提供了图片时使用。

规范示例：

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

服务器随后：规范化 query，注入固定系统提示词，应用来自环境变量的操作员过滤器，将 recency 映射到 X 日期范围，并始终使用配置的模型 / 推理努力。

images 是 Responses API 的 input_image 部分。本地文件系统路径默认禁用。这不是“搜索网页获取库存图片”。

响应结构

成功（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 key、model、base_url、原始上游 JSON 或注释数据块（URL 仅被提取到 citations 中）。请在工具结果之外诊断配置（环境变量 / 宿主 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())

真实调用会消耗模型和服务端搜索配额。单元测试使用 mock，不会访问网络。

开发

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 安装 / 运行
协议级错误、重试、超时/推理默认值
本地图像 jail（默认禁用）
规范的 MCP 调用约定（query / scope / recency / images）
可选的 Streamable HTTP 传输文档/示例
用于搜索质量的黄金集评估框架

参见开放问题。

贡献

欢迎贡献。

Fork 本项目
创建你的功能分支（git checkout -b feature/AmazingFeature）
提交你的更改（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
打开一个 Pull Request

请保持工具表面精简：优先选择一个文档完善的工具，而不是许多薄封装。

许可证

基于 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`