Metadata-Version: 2.4
Name: grok-search
Version: 0.1.0
Summary: MCP server for AI model search capabilities — dual-engine (Grok + Tavily) web search, fetch and site mapping
License-Expression: MIT
Project-URL: Homepage, https://github.com/zc-libre/grok-search
Project-URL: Repository, https://github.com/zc-libre/grok-search
Project-URL: Issues, https://github.com/zc-libre/grok-search/issues
Keywords: mcp,grok,tavily,web-search,claude-code,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.3.0
Requires-Dist: httpx[socks]>=0.28.0
Requires-Dist: mcp[cli]>=1.21.2
Requires-Dist: tenacity>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Dynamic: license-file

![这是图片](./images/title.png)
<div align="center">

<!-- # Grok Search MCP -->

[English](./docs/README_EN.md) | 简体中文

**Grok-with-Tavily MCP，为 Claude Code 提供更完善的网络访问能力**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![FastMCP](https://img.shields.io/badge/FastMCP-2.0.0+-green.svg)](https://github.com/jlowin/fastmcp)

</div>

---

## 一、概述

Grok Search MCP 是一个基于 [FastMCP](https://github.com/jlowin/fastmcp) 构建的 MCP 服务器，采用**双引擎架构**：**Grok** 负责 AI 驱动的智能搜索，**Tavily** 负责高保真网页抓取与站点映射，各取所长为 Claude Code / Cherry Studio 等LLM Client提供完整的实时网络访问能力。

```
Claude ──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 兼容的 Chat Completions 接口与 xAI 官方 Responses 接口（`/v1/responses`），通过 `GROK_API_MODE` 一键切换
- **自动时间注入**（检测时间相关查询，注入本地时间上下文）
- 一键禁用 Claude Code 官方 WebSearch/WebFetch，强制路由到本工具
- 智能重试（支持 Retry-After 头解析 + 指数退避）
- 父进程监控（Windows 下自动检测父进程退出，防止僵尸进程）

### 效果展示
我们以在`cherry studio`中配置本MCP为例，展示了`claude-opus-4.6`模型如何通过本项目实现外部知识搜集，降低幻觉率。
![](./images/wogrok.png)
如上图，**为公平实验，我们打开了claude模型内置的搜索工具**，然而opus 4.6仍然相信自己的内部常识，不查询FastAPI的官方文档，以获取最新示例。
![](./images/wgrok.png)
如上图，当打开`grok-search MCP`时，在相同的实验条件下，opus 4.6主动调用多次搜索，以**获取官方文档，回答更可靠。** 


## 二、安装

### 前置条件

- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)（推荐的 Python 包管理器）
- Claude Code

<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 用户**强烈推荐**在 WSL 中运行本项目。

</details>

### 一键安装
若之前安装过本项目，使用以下命令卸载旧版MCP。
```
claude mcp remove grok-search
```


将以下命令中的环境变量替换为你自己的值后执行。Grok 接口需为 OpenAI 兼容格式；Tavily 为可选配置，未配置时工具 `web_fetch` 和 `web_map` 不可用。

```bash
claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/zc-libre/grok-search",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "TAVILY_API_KEY": "tvly-your-tavily-key",
    "TAVILY_API_URL": "https://api.tavily.com"
  }
}'
```

<details>
<summary><b>使用 xAI Responses API + 多智能体模型</b></summary>

设置 `GROK_API_MODE=responses` 启用 xAI 官方 Responses 端点，可配合 `grok-4.20-multi-agent` 多智能体模型使用：

```bash
claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/zc-libre/grok-search",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://api.x.ai/v1",
    "GROK_API_KEY": "your-xai-api-key",
    "GROK_API_MODE": "responses",
    "GROK_MODEL": "grok-4.20-multi-agent-beta-0309",
    "GROK_REASONING_EFFORT": "high",
    "TAVILY_API_KEY": "tvly-your-tavily-key"
  }
}'
```

> **注意**：`grok-4.20-multi-agent` 系列模型**仅支持 Responses API**，使用 Chat Completions 模式会返回 HTTP 400。

</details>

<details> <summary>如果遇到 SSL / 证书验证错误</summary>

在部分企业网络或代理环境中，可能会出现类似错误：

certificate verify failed
self signed certificate in certificate chain

可以在 uvx 参数中添加 --native-tls，使其使用系统证书库：

claude mcp add-json grok-search --scope user '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--native-tls",
    "--from",
    "git+https://github.com/zc-libre/grok-search",
    "grok-search"
  ],
  "env": {
    "GROK_API_URL": "https://your-api-endpoint.com/v1",
    "GROK_API_KEY": "your-grok-api-key",
    "TAVILY_API_KEY": "tvly-your-tavily-key",
    "TAVILY_API_URL": "https://api.tavily.com"
  }
}'
</details> ```

除此之外，你还可以在`env`字段中配置更多环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `GROK_API_URL` | ✅ | - | Grok API 地址（OpenAI 兼容格式） |
| `GROK_API_KEY` | ✅ | - | Grok API 密钥 |
| `GROK_MODEL` | ❌ | `grok-4-fast` | 默认模型（设置后优先于 `~/.config/grok-search/config.json`） |
| `GROK_API_MODE` | ❌ | `chat` | API 接口模式：`chat`（Chat Completions）或 `responses`（Responses API） |
| `GROK_REASONING_EFFORT` | ❌ | - | 推理强度（仅 Responses 模式）：`low`/`medium`（4 agent）、`high`/`xhigh`（16 agent） |
| `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` | 重试最大等待秒数 |


### 验证安装

```bash
claude mcp list
```

🍟 显示连接成功后，我们**十分推荐**在 Claude 对话中输入 
```
调用 grok-search toggle_builtin_tools，关闭Claude Code's built-in WebSearch and WebFetch tools
```
工具将自动修改**项目级** `.claude/settings.json` 的 `permissions.deny`，一键禁用 Claude Code 官方的 WebSearch 和 WebFetch，从而迫使claude code调用本项目实现搜索！

### 其他 LLM 客户端配置

除 Claude Code 外，本项目同样支持所有兼容 MCP 协议的 LLM 客户端。以下是常见客户端的配置示例。

<details>
<summary><b>Cursor</b></summary>

在项目根目录创建 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局）：

```json
{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zc-libre/grok-search",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "your-grok-api-key",
        "TAVILY_API_KEY": "tvly-your-tavily-key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

编辑 `~/.codeium/windsurf/mcp_config.json`：

```json
{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zc-libre/grok-search",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "your-grok-api-key",
        "TAVILY_API_KEY": "tvly-your-tavily-key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Cline (VS Code 插件)</b></summary>

打开 Cline 设置 → MCP Servers → 添加配置：

```json
{
  "mcpServers": {
    "grok-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zc-libre/grok-search",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "your-grok-api-key",
        "TAVILY_API_KEY": "tvly-your-tavily-key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>VS Code Copilot (GitHub Copilot Chat)</b></summary>

在项目根目录创建 `.vscode/mcp.json`：

```json
{
  "servers": {
    "grok-search": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zc-libre/grok-search",
        "grok-search"
      ],
      "env": {
        "GROK_API_URL": "https://your-api-endpoint.com/v1",
        "GROK_API_KEY": "your-grok-api-key",
        "TAVILY_API_KEY": "tvly-your-tavily-key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>OpenAI Codex CLI</b></summary>

#### 一键命令添加

```bash
codex mcp add grok-search \
  --env GROK_API_URL=https://your-api-endpoint.com/v1 \
  --env GROK_API_KEY=your-grok-api-key \
  --env TAVILY_API_KEY=tvly-your-tavily-key \
  -- uvx --from git+https://github.com/zc-libre/grok-search grok-search
```

#### 手动编辑配置文件

也可以直接编辑 `~/.codex/config.toml`（全局）或项目下的 `.codex/config.toml`：

```toml
[mcp_servers.grok-search]
command = "uvx"
args = ["--from", "git+https://github.com/zc-libre/grok-search", "grok-search"]

[mcp_servers.grok-search.env]
GROK_API_URL = "https://your-api-endpoint.com/v1"
GROK_API_KEY = "your-grok-api-key"
TAVILY_API_KEY = "tvly-your-tavily-key"
```

验证：`codex mcp list`，或在 Codex TUI 中输入 `/mcp` 查看。
</details>

<details>
<summary><b>Cherry Studio</b></summary>

在 Cherry Studio 设置 → MCP 服务器中添加，选择 `stdio` 类型：

- **命令**: `uvx`
- **参数**: `--from git+https://github.com/zc-libre/grok-search grok-search`
- **环境变量**:
  - `GROK_API_URL`: `https://your-api-endpoint.com/v1`
  - `GROK_API_KEY`: `your-grok-api-key`
  - `TAVILY_API_KEY`: `tvly-your-tavily-key`

</details>

> 💡 所有客户端均支持上述环境变量表中的全部配置项。

## 三、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`: 已缓存的信源数量

### `x_search` — X/Twitter 搜索（Responses API）

通过 xAI 的 x_search 工具搜索 X（原 Twitter）上的帖子。**仅在 `GROK_API_MODE=responses` 时可用。**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | ✅ | - | 搜索查询语句 |
| `x_handles` | string | ❌ | `""` | 限定搜索的 X 账号（逗号分隔，无需 @，最多 10 个） |
| `excluded_x_handles` | string | ❌ | `""` | 排除的 X 账号（逗号分隔，最多 10 个） |
| `from_date` | string | ❌ | `""` | 起始日期（ISO8601 格式，如 `2026-03-01T00:00:00Z`） |
| `to_date` | string | ❌ | `""` | 截止日期（ISO8601 格式） |
| `image_understanding` | bool | ❌ | `false` | 分析帖子中的图片 |
| `video_understanding` | bool | ❌ | `false` | 分析帖子中的视频 |
| `model` | string | ❌ | `null` | 按次指定 Grok 模型 ID |

返回值结构同 `web_search`。

### `get_sources` — 获取信源

通过 `session_id` 获取对应 `web_search` 或 `x_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 自动脱敏）。

### `switch_model` — 模型切换

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | ✅ | 模型 ID（如 `"grok-4-fast"`, `"grok-2-latest"`） |

切换后配置持久化到 `~/.config/grok-search/config.json`，跨会话保持。

### `toggle_builtin_tools` — 工具路由控制

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `action` | string | ❌ | `"status"` | `"on"` 禁用官方工具 / `"off"` 启用官方工具 / `"status"` 查看状态 |

修改项目级 `.claude/settings.json` 的 `permissions.deny`，一键禁用 Claude Code 官方的 WebSearch 和 WebFetch。

### `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` 端点（`GROK_API_MODE=chat`）；设置 `GROK_API_MODE=responses` 后切换到 xAI 官方 Responses 端点（`/responses`），可启用服务端 `web_search`、`x_search` 等工具。
</details>

<details>
<summary>
Q: 如何验证配置？
</summary>
A: 在 Claude 对话中说"显示 grok-search 配置信息"，将自动测试 API 连接并显示结果。
</details>

## 许可证

[MIT License](LICENSE)

---

<div align="center">

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

[![Star History Chart](https://api.star-history.com/svg?repos=zc-libre/grok-search&type=date&legend=top-left)](https://www.star-history.com/#zc-libre/grok-search&type=date&legend=top-left)
</div>
