GitHub - shuiyell/GrokSearch: Integrate Grok's powerful real-time search capabilities into Claude via the MCP protocol!

English | 简体中文

通过 MCP 协议将 Grok 搜索能力集成到 Claude，显著增强文档检索与事实核查能力

概述

Grok Search MCP 是一个基于 FastMCP 构建的 MCP（Model Context Protocol）服务器，通过转接第三方平台（如 Grok）的强大搜索能力，为 Claude、Claude Code 等 AI 模型提供实时网络搜索功能。

核心价值

突破知识截止限制：让 Claude 访问最新的网络信息，不再受训练数据时间限制
增强事实核查：实时搜索验证信息的准确性和时效性
结构化输出：返回包含标题、链接、摘要的标准化 JSON，便于 AI 模型理解与引用
即插即用：通过 MCP 协议无缝集成到 Claude Desktop、Claude Code 等客户端

工作流程：Claude → MCP → Grok API → 搜索/抓取 → 结构化返回

💡 更多选择Grok search 的理由

与其他搜索方案对比：

特性	Grok Search MCP	Google Custom Search API	Bing Search API	SerpAPI
AI 优化结果	✅ 专为 AI 理解优化	❌ 通用搜索结果	❌ 通用搜索结果	❌ 通用搜索结果
内容摘要质量	✅ AI 生成高质量摘要	⚠️ 需二次处理	⚠️ 需二次处理	⚠️ 需二次处理
实时性	✅ 实时网络数据	✅ 实时	✅ 实时	✅ 实时
集成复杂度	✅ MCP 即插即用	⚠️ 需自行开发	⚠️ 需自行开发	⚠️ 需自行开发
返回格式	✅ AI 友好 JSON	⚠️ 需格式化	⚠️ 需格式化	⚠️ 需格式化

功能特性

✅ OpenAI 兼容接口，环境变量配置
✅ 实时网络搜索 + 网页内容抓取
✅ 支持指定搜索平台（Twitter、Reddit、GitHub 等）
✅ 配置测试工具（连接测试 + API Key 脱敏）
✅ 动态模型切换（支持切换不同 Grok 模型并持久化保存）
✅ 工具路由控制（一键禁用官方 WebSearch/WebFetch，强制使用 GrokSearch）
✅ 可扩展架构，支持添加其他搜索 Provider

安装教程

Step 0.前期准备（若已经安装uv则跳过该步骤）

Details

Python 环境：

Python 3.10 或更高版本
已配置 Claude Code 或 Claude Desktop

uv 工具（推荐的 Python 包管理器）：

请确保您已成功安装 uv 工具：

Windows 安装 uv

在 PowerShell 中运行以下命令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

💡 重要提示 ：我们 强烈推荐 Windows 用户在 WSL（Windows Subsystem for Linux）中运行本项目！

Linux/macOS 安装 uv

使用 curl 或 wget 下载并安装：

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

# 或使用 wget
wget -qO- https://astral.sh/uv/install.sh | sh

Step 1. 安装 Grok Search MCP

使用 claude mcp add-json 一键安装并配置： 注意： 需要替换 GROK_API_URL 以及 GROK_API_KEY这两个字段为你自己的站点以及密钥，目前只支持openai格式，所以如果需要使用grok，也需要使用转为openai格式的grok镜像站

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/GuDaStudio/GrokSearch",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-api-key-here"
  }
}'

Step 2. 验证安装 & 检查MCP配置

claude mcp list

应能看到 grok-search 服务器已注册。

配置完成后，强烈建议在 Claude 对话中运行配置测试，以确保一切正常：

在 Claude 对话中输入：

请测试 Grok Search 的配置

或直接说：

显示 grok-search 配置信息

工具会自动执行以下检查：

✅ 验证环境变量是否正确加载
✅ 测试 API 连接（向 /models 端点发送请求）
✅ 显示响应时间和可用模型数量
✅ 识别并报告任何配置错误

如果看到 ❌ 连接失败 或 ⚠️ 连接异常，请检查：

API URL 是否正确
API Key 是否有效
网络连接是否正常

Step 3. 配置系统提示词

为了更好的使用Grok Search 可以通过配置Claude Code或者类似的系统提示词来对整体Vibe Coding Cli进行优化，以Claude Code 为例可以编辑 ~/.claude/CLAUDE.md中追加下面内容，提供了两版使用详细版更能激活工具的能力：

💡 提示：现在可以使用 toggle_builtin_tools 工具一键禁用官方 WebSearch/WebFetch，强制路由到 GrokSearch！

精简版提示词

# Grok Search 提示词 精简版
## 激活与路由
**触发**：网络搜索/网页抓取/最新信息查询时自动激活
**替换**：尽可能使用 Grok-search的工具替换官方原生search以及fetch功能

## 工具矩阵

| Tool | Parameters | Output | Use Case |
|------|------------|--------|----------|
| `web_search` | `query`(必填), `platform`/`min_results`/`max_results`(可选) | `[{title,url,content}]` | 多源聚合/事实核查/最新资讯 |
| `web_fetch` | `url`(必填) | Structured Markdown | 完整内容获取/深度分析 |
| `get_config_info` | 无 | `{api_url,status,test}` | 连接诊断 |
| `switch_model` | `model`(必填) | `{status,previous_model,current_model}` | 切换Grok模型/性能优化 |
| `toggle_builtin_tools` | `action`(可选: on/off/status) | `{blocked,deny_list,file}` | 禁用/启用官方工具 |

## 执行策略
**查询构建**：广度用 `web_search`，深度用 `web_fetch`，特定平台设 `platform` 参数
**搜索执行**：优先摘要 → 关键 URL 补充完整内容 → 结果不足调整查询重试（禁止放弃）
**结果整合**：交叉验证 + **强制标注来源** `[标题](URL)` + 时间敏感信息注明日期

## 错误恢复

连接失败 → `get_config_info` 检查 | 无结果 → 放宽查询条件 | 超时 → 搜索替代源


## 核心约束

✅ 强制 GrokSearch 工具 + 输出必含来源引用 + 失败必重试 + 关键信息必验证
❌ 禁止无来源输出 + 禁止单次放弃 + 禁止未验证假设

详细版提示词

💡 Grok Search Enhance 系统提示词（详细版）（点击展开）

  # Grok Search Enhance 系统提示词（详细版）

  ## 0. Module Activation
  **触发条件**：当需要执行以下操作时，自动激活本模块：
  - 网络搜索 / 信息检索 / 事实核查
  - 获取网页内容 / URL 解析 / 文档抓取
  - 查询最新信息 / 突破知识截止限制

  ## 1. Tool Routing Policy

  ### 强制替换规则
  | 需求场景 | ❌ 禁用 (Built-in) | ✅ 强制使用 (GrokSearch) |
  | :--- | :--- | :--- |
  | 网络搜索 | `WebSearch` | `mcp__grok-search__web_search` |
  | 网页抓取 | `WebFetch` | `mcp__grok-search__web_fetch` |
  | 配置诊断 | N/A | `mcp__grok-search__get_config_info` |

  ### 工具能力矩阵

| Tool | Parameters | Output | Use Case |
|------|------------|--------|----------|
| `web_search` | `query`(必填), `platform`/`min_results`/`max_results`(可选) | `[{title,url,content}]` | 多源聚合/事实核查/最新资讯 |
| `web_fetch` | `url`(必填) | Structured Markdown | 完整内容获取/深度分析 |
| `get_config_info` | 无 | `{api_url,status,test}` | 连接诊断 |
| `switch_model` | `model`(必填) | `{status,previous_model,current_model}` | 切换Grok模型/性能优化 |
| `toggle_builtin_tools` | `action`(可选: on/off/status) | `{blocked,deny_list,file}` | 禁用/启用官方工具 |


  ## 2. Search Workflow

  ### Phase 1: 查询构建 (Query Construction)
  1.  **意图识别**：分析用户需求，确定搜索类型：
      - **广度搜索**：多源信息聚合 → 使用 `web_search`
      - **深度获取**：单一 URL 完整内容 → 使用 `web_fetch`
  2.  **参数优化**：
      - 若需聚焦特定平台，设置 `platform` 参数
      - 根据需求复杂度调整 `min_results` / `max_results`

  ### Phase 2: 搜索执行 (Search Execution)
  1.  **首选策略**：优先使用 `web_search` 获取结构化摘要
  2.  **深度补充**：若摘要不足以回答问题，对关键 URL 调用 `web_fetch` 获取完整内容
  3.  **迭代检索**：若首轮结果不满足需求，**调整查询词**后重新搜索（禁止直接放弃）

  ### Phase 3: 结果整合 (Result Synthesis)
  1.  **信息验证**：交叉比对多源结果，识别矛盾信息
  2.  **时效标注**：对时间敏感信息，**必须**标注信息来源与时间
  3.  **引用规范**：输出中**强制包含**来源 URL，格式：`[标题](URL)`

  ## 3. Error Handling

  | 错误类型 | 诊断方法 | 恢复策略 |
  | :--- | :--- | :--- |
  | 连接失败 | 调用 `get_config_info` 检查配置 | 提示用户检查 API URL / Key |
  | 无搜索结果 | 检查 query 是否过于具体 | 放宽搜索词，移除限定条件 |
  | 网页抓取超时 | 检查 URL 可访问性 | 尝试搜索替代来源 |
  | 内容被截断 | 检查目标页面结构 | 分段抓取或提示用户直接访问 |

  ## 4. Anti-Patterns

  | ❌ 禁止行为 | ✅ 正确做法 |
  | :--- | :--- |
  | 搜索后不标注来源 | 输出**必须**包含 `[来源](URL)` 引用 |
  | 单次搜索失败即放弃 | 调整参数后至少重试 1 次 |
  | 假设网页内容而不抓取 | 对关键信息**必须**调用 `web_fetch` 验证 |
  | 忽略搜索结果的时效性 | 时间敏感信息**必须**标注日期 |

  ---
  模块说明：
  - 强制替换：明确禁用内置工具，强制路由到 GrokSearch
  - 三工具覆盖：web_search + web_fetch + get_config_info
  - 错误处理：包含配置诊断的恢复策略
  - 引用规范：强制标注来源，符合信息可追溯性要求

详细项目介绍

MCP 工具说明

本项目提供五个 MCP 工具：

`web_search` - 网络搜索

参数	类型	必填	默认值	说明
`query`	string	✅	-	搜索查询语句
`platform`	string	❌	`""`	聚焦搜索平台（如 `"Twitter"`, `"GitHub, Reddit"`）
`min_results`	int	❌	`3`	最少返回结果数
`max_results`	int	❌	`10`	最多返回结果数

返回：包含 title、url、content 的 JSON 数组

返回示例（点击展开）

[
  {
    "title": "Claude Code - Anthropic官方CLI工具",
    "url": "https://claude.com/claude-code",
    "description": "Anthropic推出的官方命令行工具，支持MCP协议集成，提供代码生成和项目管理功能"
  },
  {
    "title": "Model Context Protocol (MCP) 技术规范",
    "url": "https://modelcontextprotocol.io/docs",
    "description": "MCP协议官方文档，定义了AI模型与外部工具的标准化通信接口"
  },
  {
    ...
  }
]

`web_fetch` - 网页内容抓取

参数	类型	必填	说明
`url`	string	✅	目标网页 URL

功能：获取完整网页内容并转换为结构化 Markdown，保留标题层级、列表、表格、代码块等元素

返回示例（点击展开）

---
source: https://modelcontextprotocol.io/docs/concepts/architecture
title: MCP 架构设计文档
fetched_at: 2024-01-15T10:30:00Z
---

# MCP 架构设计文档

## 目录
- [核心概念](#核心概念)
- [协议层次](#协议层次)
- [通信模式](#通信模式)

## 核心概念

Model Context Protocol (MCP) 是一个标准化的通信协议，用于连接 AI 模型与外部工具和数据源。
...

更多信息请访问 [官方文档](https://modelcontextprotocol.io)

`get_config_info` - 配置信息查询

无需参数。显示配置状态、测试 API 连接、返回响应时间和可用模型数量（API Key 自动脱敏）

返回示例（点击展开）

{
  "api_url": "https://YOUR-API-URL/grok/v1",
  "api_key": "sk-a*****************xyz",
  "config_status": "✅ 配置完整",
  "connection_test": {
    "status": "✅ 连接成功",
    "message": "成功获取模型列表 (HTTP 200)，共 x 个模型",
    "response_time_ms": 234.56
  }
}

`switch_model` - 模型切换

参数	类型	必填	说明
`model`	string	✅	要切换到的模型 ID（如 `"grok-4-fast"`, `"grok-2-latest"`, `"grok-vision-beta"`）

功能：

切换用于搜索和抓取操作的默认 Grok 模型
配置自动持久化到 ~/.config/grok-search/config.json
支持跨会话保持设置
适用于性能优化或质量对比测试

返回示例（点击展开）

{
  "status": "✅ 成功",
  "previous_model": "grok-4-fast",
  "current_model": "grok-2-latest",
  "message": "模型已从 grok-4-fast 切换到 grok-2-latest",
  "config_file": "/home/user/.config/grok-search/config.json"
}

使用示例：

在 Claude 对话中输入：

请将 Grok 模型切换到 grok-2-latest

或直接说：

切换模型到 grok-vision-beta

`toggle_builtin_tools` - 工具路由控制

参数	类型	必填	默认值	说明
`action`	string	❌	`"status"`	操作类型：`"on"`/`"enable"`(禁用官方工具)、`"off"`/`"disable"`(启用官方工具)、`"status"`/`"check"`(查看状态)

功能：

控制项目级 .claude/settings.json 的 permissions.deny 配置
禁用/启用 Claude Code 官方的 WebSearch 和 WebFetch 工具
强制路由到 GrokSearch MCP 工具
自动定位项目根目录（查找 .git）
保留其他配置项

返回示例（点击展开）

{
  "blocked": true,
  "deny_list": ["WebFetch", "WebSearch"],
  "file": "/path/to/project/.claude/settings.json",
  "message": "官方工具已禁用"
}

使用示例：

# 禁用官方工具（推荐）
禁用官方的 search 和 fetch 工具

# 启用官方工具
启用官方的 search 和 fetch 工具

# 检查当前状态
显示官方工具的禁用状态

项目架构

（点击展开）

src/grok_search/
├── config.py          # 配置管理（环境变量）
├── server.py          # MCP 服务入口（注册工具）
├── logger.py          # 日志系统
├── utils.py           # 格式化工具
└── providers/
    ├── base.py        # SearchProvider 基类
    └── grok.py        # Grok API 实现

常见问题

Q: 如何获取 Grok API 访问权限？ A: 注册第三方平台 → 获取 API Endpoint 和 Key → 使用 claude mcp add-json 配置

Q: 配置后如何验证？ A: 在 Claude 对话中说"显示 grok-search 配置信息"，查看连接测试结果

许可证

本项目采用 MIT License 开源。

如果这个项目对您有帮助，请给个 ⭐ Star！

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
docs		docs
images		images
src/grok_search		src/grok_search
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

概述

核心价值

功能特性

安装教程

Step 0.前期准备（若已经安装uv则跳过该步骤）

Windows 安装 uv

Linux/macOS 安装 uv

Step 1. 安装 Grok Search MCP

Step 2. 验证安装 & 检查MCP配置

Step 3. 配置系统提示词

精简版提示词

详细版提示词

详细项目介绍

MCP 工具说明

`web_search` - 网络搜索

`web_fetch` - 网页内容抓取

`get_config_info` - 配置信息查询

`switch_model` - 模型切换

`toggle_builtin_tools` - 工具路由控制

项目架构

常见问题

许可证

About

Uh oh!

Releases

Packages

Languages

License

shuiyell/GrokSearch

Folders and files

Latest commit

History

Repository files navigation

概述

核心价值

功能特性

安装教程

Step 0.前期准备（若已经安装uv则跳过该步骤）

Windows 安装 uv

Linux/macOS 安装 uv

Step 1. 安装 Grok Search MCP

Step 2. 验证安装 & 检查MCP配置

Step 3. 配置系统提示词

精简版提示词

详细版提示词

详细项目介绍

MCP 工具说明

web_search - 网络搜索

web_fetch - 网页内容抓取

get_config_info - 配置信息查询

switch_model - 模型切换

toggle_builtin_tools - 工具路由控制

项目架构

常见问题

许可证

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`web_search` - 网络搜索

`web_fetch` - 网页内容抓取

`get_config_info` - 配置信息查询

`switch_model` - 模型切换

`toggle_builtin_tools` - 工具路由控制

Packages