内容
<div align="center">
<!-- # Grok Search MCP -->
[English](./docs/README_EN.md) | 简体中文
**Grok-with-Tavily MCP，为 Codex 提供更完善的网络访问能力**
[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/jlowin/fastmcp)
</div>
---
## 一、概述
Grok Search MCP 是一个基于 [FastMCP](https://github.com/jlowin/fastmcp) 构建的 MCP 服务器，采用**双引擎架构**：**Grok** 负责 AI 驱动的智能搜索，**Tavily** 负责高保真网页抓取与站点映射，各取所长为 Codex 提供完整的实时网络访问能力。
### 项目来源与修改说明
本项目基于 [GuDaStudio/GrokSearch](https://github.com/GuDaStudio/GrokSearch) 修改而来，保留原项目的 Grok 搜索、Tavily 抓取/映射和 Firecrawl 降级能力。
本分支的主要修改目的，是让该 MCP 服务更稳定地作为 **Codex 可用的联网搜索工具**运行：修复 OpenAI 兼容接口裸域名缺少 `/v1` 时的配置问题，增强 `/models` 与流式响应的格式校验，避免上游返回 HTML 或空响应时被误判为成功；同时补充 `TAVILY_ENABLED` 开关生效逻辑、额外信源分配策略、Codex stdio MCP instructions、`get_codex_setup` 配置辅助工具，以及项目级 `.codex/config.toml` 示例。
这些改动的作用是降低 Codex 调用搜索/抓取工具时的空返回和误配置概率，并让用户可以更容易地通过 `codex mcp add` 或本地 `.codex/config.toml` 接入该 MCP。
```
Codex ──MCP──► Grok Search Server
├─ web_search ───► Grok API（AI 搜索）
├─ web_fetch ───► Tavily Extract → Firecrawl Scrape（内容抓取，自动降级）
└─ web_map ───► Tavily Map（站点映射）
```
### 功能特性
- **双引擎**：Grok 搜索 + Tavily 抓取/映射，互补协作
- **Firecrawl 托底**：Tavily 提取失败时自动降级到 Firecrawl Scrape，支持空内容自动重试
- **OpenAI 兼容接口**，支持任意 Grok 镜像站
- **Codex 兼容**：提供 stdio MCP server instructions、Codex 配置示例和 `get_codex_setup` 配置辅助工具
- **自动时间注入**（检测时间相关查询，注入本地时间上下文）
- 智能重试（支持 Retry-After 头解析 + 指数退避）
- 父进程监控（Windows 下自动检测父进程退出，防止僵尸进程）
## 二、安装
### 前置条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)（推荐的 Python 包管理器）
- Codex
- 如从私有 GitHub 仓库安装，请先确保当前终端已通过 `gh auth login` 或 Git 凭据具备访问该仓库的权限
<details>
<summary><b>安装 uv</b></summary>
```bash
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
> Windows 用户可直接在 PowerShell 中运行；如遇证书问题，可参考下方 `--native-tls` 示例。
</details>
### 安装到 Codex（推荐）
如果之前安装过同名 MCP，先移除旧配置：
```powershell
codex mcp remove grok-search
```
然后安装当前项目：
```powershell
codex mcp add grok-search `
--env GROK_API_URL=https://your-api-endpoint.com/v1 `
--env GROK_API_KEY=your-grok-api-key `
--env GROK_MODEL=grok-4-fast `
--env TAVILY_API_KEY=tvly-your-tavily-key `
--env TAVILY_API_URL=https://api.tavily.com `
-- uvx --from git+https://github.com/losalexandra/GrokSearch-Codex-MCP grok-search
```
说明：
- `GROK_API_URL` 需要是 OpenAI 兼容接口；如果只填写裸域名，程序会自动补齐 `/v1`。
- `GROK_API_KEY` 为必填。
- `GROK_MODEL` 可选，默认 `grok-4-fast`。
- `TAVILY_API_KEY` 可选；未配置时 `web_fetch` / `web_map` 不可用。
- 真实密钥不要写入仓库，应通过 `codex mcp add --env`、用户级 `~/.codex/config.toml` 或当前终端环境变量传入。
验证 Codex 配置：
```powershell
codex mcp list
codex mcp get grok-search
```
进入 Codex 后可调用：
```text
调用 grok-search get_config_info 检查配置
```
### 本地开发模式
本仓库包含项目级 `.codex/config.toml`：
```toml
[mcp_servers.grok-search]
command = "uv"
args = ["run", "grok-search"]
```
在当前仓库中启动 Codex 时，它可以直接读取该配置，用本地源码运行 MCP。此方式适合开发和调试；密钥仍然不要写入 `.codex/config.toml`。
### Claude 使用说明
本仓库面向 Codex 做了适配和文档整理。如果需要在 Claude / Claude Code 中使用 Grok Search MCP，推荐直接使用原作者仓库：[GuDaStudio/GrokSearch](https://github.com/GuDaStudio/GrokSearch)。
### 环境变量
| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `GROK_API_URL` | ✅ | - | Grok API 地址（OpenAI 兼容格式） |
| `GROK_API_KEY` | ✅ | - | Grok API 密钥 |
| `GROK_MODEL` | ❌ | `grok-4-fast` | 默认模型（设置后优先于 `~/.config/grok-search/config.json`） |
| `TAVILY_API_KEY` | ❌ | - | Tavily API 密钥（用于 web_fetch / web_map） |
| `TAVILY_API_URL` | ❌ | `https://api.tavily.com` | Tavily API 地址 |
| `TAVILY_ENABLED` | ❌ | `true` | 是否启用 Tavily |
| `FIRECRAWL_API_KEY` | ❌ | - | Firecrawl API 密钥（Tavily 失败时托底） |
| `FIRECRAWL_API_URL` | ❌ | `https://api.firecrawl.dev/v2` | Firecrawl API 地址 |
| `GROK_DEBUG` | ❌ | `false` | 调试模式 |
| `GROK_LOG_LEVEL` | ❌ | `INFO` | 日志级别 |
| `GROK_LOG_DIR` | ❌ | `logs` | 日志目录 |
| `GROK_RETRY_MAX_ATTEMPTS` | ❌ | `3` | 最大重试次数 |
| `GROK_RETRY_MULTIPLIER` | ❌ | `1` | 重试退避乘数 |
| `GROK_RETRY_MAX_WAIT` | ❌ | `10` | 重试最大等待秒数 |
## 三、MCP 工具介绍
<details>
<summary>本项目提供多个 MCP 工具（展开查看）</summary>
### `web_search` — AI 网络搜索
通过 Grok API 执行 AI 驱动的网络搜索，默认仅返回 Grok 的回答正文，并返回 `session_id` 以便后续获取信源。
`web_search` 输出不展开信源，仅返回 `sources_count`；信源会按 `session_id` 缓存在服务端，可用 `get_sources` 拉取。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | ✅ | - | 搜索查询语句 |
| `platform` | string | ❌ | `""` | 聚焦平台（如 `"Twitter"`, `"GitHub, Reddit"`） |
| `model` | string | ❌ | `null` | 按次指定 Grok 模型 ID |
| `extra_sources` | int | ❌ | `0` | 额外补充信源数量（Tavily/Firecrawl，可为 0 关闭） |
自动检测查询中的时间相关关键词（如"最新""今天""recent"等），注入本地时间上下文以提升时效性搜索的准确度。
返回值（结构化字典）：
- `session_id`: 本次查询的会话 ID
- `content`: Grok 回答正文（已自动剥离信源）
- `sources_count`: 已缓存的信源数量
### `get_sources` — 获取信源
通过 `session_id` 获取对应 `web_search` 的全部信源。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `session_id` | string | ✅ | `web_search` 返回的 `session_id` |
返回值（结构化字典）：
- `session_id`
- `sources_count`
- `sources`: 信源列表（每项包含 `url`，可能包含 `title`/`description`/`provider`）
### `web_fetch` — 网页内容抓取
通过 Tavily Extract API 获取完整网页内容，返回 Markdown 格式。Tavily 失败时自动降级到 Firecrawl Scrape 进行托底抓取。
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | ✅ | 目标网页 URL |
### `web_map` — 站点结构映射
通过 Tavily Map API 遍历网站结构，发现 URL 并生成站点地图。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `url` | string | ✅ | - | 起始 URL |
| `instructions` | string | ❌ | `""` | 自然语言过滤指令 |
| `max_depth` | int | ❌ | `1` | 最大遍历深度（1-5） |
| `max_breadth` | int | ❌ | `20` | 每页最大跟踪链接数（1-500） |
| `limit` | int | ❌ | `50` | 总链接处理数上限（1-500） |
| `timeout` | int | ❌ | `150` | 超时秒数（10-150） |
### `get_config_info` — 配置诊断
无需参数。显示所有配置状态、测试 Grok API 连接、返回响应时间和可用模型列表（API Key 自动脱敏）。
### `get_codex_setup` — Codex 配置辅助
无需参数。返回 Codex stdio MCP 的 `codex mcp add` 命令和 `config.toml` 示例，所有密钥均以占位符展示。
### `switch_model` — 模型切换
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | ✅ | 模型 ID（如 `"grok-4-fast"`, `"grok-2-latest"`） |
切换后配置持久化到 `~/.config/grok-search/config.json`，跨会话保持。
### `search_planning` — 搜索规划
结构化搜索规划脚手架（分阶段、多轮），用于在执行复杂搜索前先生成可执行的搜索计划。
</details>
## 四、常见问题
<details>
<summary>
Q: 必须同时配置 Grok 和 Tavily 吗？
</summary>
A: Grok（`GROK_API_URL` + `GROK_API_KEY`）为必填，提供核心搜索能力。Tavily 和 Firecrawl 均为可选：配置 Tavily 后 `web_fetch` 优先使用 Tavily Extract，失败时降级到 Firecrawl Scrape；两者均未配置时 `web_fetch` 将返回配置错误提示。`web_map` 依赖 Tavily。
</details>
<details>
<summary>
Q: Grok API 地址需要什么格式？
</summary>
A: 需要 OpenAI 兼容格式的 API 地址（支持 `/chat/completions` 和 `/models` 端点）。如使用官方 Grok，需通过兼容 OpenAI 格式的镜像站访问。
</details>
<details>
<summary>
Q: 如何验证配置？
</summary>
A: 在 Codex 中调用 `grok-search get_config_info`，工具会自动测试 API 连接并显示模型列表、配置状态和脱敏后的密钥信息。
</details>
## 许可证
[MIT License](LICENSE)
---
<div align="center">
**如果这个项目对您有帮助，请给个 Star！**
[](https://www.star-history.com/#losalexandra/GrokSearch-Codex-MCP&type=date&legend=top-left)
</div>
