<div align="center">

# 知乎 MCP

### 让 Agent 搜索知乎、阅读原文、调用 AI 直答

连接 **知乎主站搜索** 与 **知乎直答 Zhida**，为资料搜集、技术调研和话题追踪提供 11 个 MCP 工具。

<p>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&amp;logo=python&amp;logoColor=white" alt="Python 3.10+"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-stdio-111827?style=for-the-badge" alt="MCP stdio"></a>
  <a href="https://www.zhihu.com/"><img src="https://img.shields.io/badge/Zhihu-Search_%2B_Zhida-0084FF?style=for-the-badge&amp;logo=zhihu&amp;logoColor=white" alt="知乎 Search + Zhida"></a>
</p>
<p>
  <a href="#codex"><img src="https://img.shields.io/badge/Codex-Setup-10A37F?style=flat-square" alt="Codex 接入指南"></a>
  <a href="#claude-desktop"><img src="https://img.shields.io/badge/Claude-Setup-D97757?style=flat-square&amp;logo=claude&amp;logoColor=white" alt="Claude 接入指南"></a>
  <a href="#tools"><img src="https://img.shields.io/badge/MCP_Tools-11-6366F1?style=flat-square" alt="11 MCP tools"></a>
  <a href="https://github.com/we1005/zhihu-mcp/stargazers"><img src="https://img.shields.io/github/stars/we1005/zhihu-mcp?style=flat-square&amp;logo=github" alt="GitHub stars"></a>
</p>

[快速开始](#quick-start) · [客户端配置](#clients) · [工具清单](#tools) · [使用示例](#examples) · [实测与文档](#docs)

</div>

---

## ✨ 能做什么

| 能力 | 适合的任务 |
| :--- | :--- |
| 🔎 **主站搜索** | 按关键词找回答、文章，获取搜索建议与热搜 |
| 📖 **原文读取** | 抓取回答和文章，返回正文、作者、链接、赞数与时间信息 |
| ⚡ **搜、筛、抓一体化** | 按赞数、内容类型和更新时间筛选，再并发抓取正文 |
| 🛰️ **多话题监控** | 分别搜索多个话题，合并去重，支持传入上次已读 ID |
| 💬 **AI 直答** | 调用 FAST / DEEP_SEARCH / AUTO，读取回答、来源卡片与会话 |
| 🍪 **本地 Cookie 管理** | 浏览器页面验证、保存和备份 Cookie，工具调用前检查登录状态 |

服务通过 **stdio** 与 MCP 客户端通信。核心网络逻辑使用 Python 标准库，MCP 入口依赖 `mcp` v1 SDK；Cookie 管理页面使用内置 HTTP 服务。

```mermaid
flowchart LR
    A[Codex / Claude / 其他 MCP Agent] -->|stdio| B[知乎 MCP]
    B --> C[主站搜索]
    B --> D[AI 直答]
    C --> E[回答 / 文章原文]
    D --> F[回答 / 来源卡片]
    F -->|回查知乎来源| E
    E --> G[Agent 去重、核验、摘要]
    H[本地 Cookie 管理] -. 登录凭证 .-> B
```

<a id="quick-start"></a>

## 🚀 快速开始

需要 **Python 3.10+**、可访问知乎的网络，以及你自己的知乎登录 Cookie。当前验证环境为 Python 3.14.5 / MCP SDK 1.30.0。

### 1. 克隆并安装

```bash
git clone https://github.com/we1005/zhihu-mcp.git
cd zhihu-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```

运行依赖限定为 `mcp>=1.30,<2`，与当前 FastMCP v1 接口保持一致。下文命令使用 macOS / Linux 路径；Windows 请将 `.venv/bin/python` 替换为 `.venv\Scripts\python.exe`。

### 2. 保存 Cookie

```bash
.venv/bin/python cookie_admin.py --open
```

打开本地管理页 **http://127.0.0.1:8899/** 后：

1. 在浏览器中登录知乎，打开开发者工具的 **Network** 面板。
2. 选择一条发往 `zhihu.com` 的请求，复制请求头中的 **Cookie 值**。
3. 将值粘贴到管理页，点击「验证并保存」。

Cookie 需要包含有效的 `d_c0` 和 `z_c0`。保存位置为仓库目录下的 `cookie.txt`，旧值自动备份；二者都已加入 `.gitignore`。当前健康检查和正文抓取使用这一默认位置，建议按此布局配置。

### 3. 验证并连接客户端

先用 CLI 做一次登录状态检查：

```bash
echo '{"tool":"zhihu_health_check","args":{}}' | \
  .venv/bin/python mcp_server.py --cli
```

检查响应中的 `result.live_ok` 是否为 `true`，再按下方配置接入。stdio 服务由 MCP 客户端按需启动，无需先在终端常驻运行。

<a id="clients"></a>

## 🔌 接入客户端

将示例中的 `/absolute/path/to/zhihu-mcp` 替换为克隆目录的**绝对路径**。`command` 必须指向已安装依赖的虚拟环境 Python。

### Codex

在 Codex 配置文件中加入以下内容。默认位置是 `~/.codex/config.toml`；设置了 `CODEX_HOME` 时，使用该目录中的 `config.toml`。

```toml
[mcp_servers.zhida]
command = "/absolute/path/to/zhihu-mcp/.venv/bin/python"
args = ["/absolute/path/to/zhihu-mcp/mcp_server.py"]
cwd = "/absolute/path/to/zhihu-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.zhida.env]
ZHIHU_COOKIE_PATH = "/absolute/path/to/zhihu-mcp/cookie.txt"
```

也可先用 CLI 注册，再在配置中补充上述超时设置：

```bash
codex mcp add zhida \
  --env ZHIHU_COOKIE_PATH=/absolute/path/to/zhihu-mcp/cookie.txt \
  -- /absolute/path/to/zhihu-mcp/.venv/bin/python \
     /absolute/path/to/zhihu-mcp/mcp_server.py
```

已有 `zhida` 条目时直接编辑，避免重复注册。重启客户端后，在 Codex CLI 使用 `/mcp` 查看连接，再调用 `zhihu_health_check` 验证实际可用性。

配置依据：[OpenAI 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。本项目的 [Codex 接入记录](docs/codex-integration-2026-9-9.md) 包含 11 个工具发现结果和 7 个工具的实际调用结果。

### Claude Desktop

macOS 配置文件：`~/Library/Application Support/Claude/claude_desktop_config.json`。

```json
{
  "mcpServers": {
    "zhida": {
      "command": "/absolute/path/to/zhihu-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/zhihu-mcp/mcp_server.py"],
      "env": {
        "ZHIHU_COOKIE_PATH": "/absolute/path/to/zhihu-mcp/cookie.txt"
      }
    }
  }
}
```

保存后重启 Claude Desktop。其他支持本地 stdio 的 MCP 客户端可使用相同命令和参数。

<details>
<summary><b>可选：MCP 与 Cookie 管理页一起启动</b></summary>

在客户端配置的 `args` 中追加 `--with-admin`，即可随 MCP 启动本地管理页。也可以手动运行：

```bash
.venv/bin/python mcp_server.py --with-admin
```

默认端口为 `8899`。端口冲突时使用 `--with-admin=9000`，或单独运行管理页：

```bash
.venv/bin/python cookie_admin.py 9000 --open
```

同时运行多个 MCP 客户端时，建议保持纯 stdio 配置，按需单独打开管理页。

</details>

<a id="tools"></a>

## 🧰 11 个工具

| 工具 | 用途 | 使用提示 |
| :--- | :--- | :--- |
| `zhihu_health_check` | 检查 Cookie 和登录状态 | 首次调用或定时任务开始时使用 |
| `zhihu_search` | 主站关键词搜索 | 支持类型、分页和条数限制 |
| `zhihu_search_suggest` | 获取搜索建议 | 扩展检索词 |
| `zhihu_search_hot` | 获取当前热搜 | 发现热点话题 |
| `zhihu_search_and_fetch` | 单话题搜索、筛选、抓取正文 | 优先用于资料搜集 |
| `zhihu_monitor_topics` | 多话题并发搜索与去重 | 保存 `all_seen_ids` 可实现增量检索 |
| `zhida_fetch_zhihu` | 读取单篇回答或文章 | 默认返回 `content_text` 纯文本 |
| `zhida_get_session` | 读取直答会话及来源 | 使用已有 `session_id` |
| `zhida_list_sessions` | 读取当前账号的直答会话历史 | 返回账号个人会话信息 |
| `zhida_at_search` | 搜索作者及 @ 提及信息 | 用于作者线索检索 |
| `zhida_ask` | 发起或追问 AI 直答 | **消耗直答额度，并留下会话历史** |

详细参数、返回结构和错误处理见 [AGENTS.md](AGENTS.md)。赞数是候选筛选信号，最终内容质量仍需结合原文判断。

<a id="examples"></a>

## 💡 使用示例

### 让 Agent 搜集 AI Infra 资料

接入后，可以直接提出：

> 用知乎 MCP 搜集 20 篇 AI Infra 相关回答或文章，覆盖推理服务、GPU 调度、训练通信和 KV Cache。先检查登录状态，再按多个关键词检索；去重后阅读原文，逐篇给出标题、作者、链接和摘要。若不足 20 篇，说明实际找到的数量。

单话题 CLI 示例：

```bash
echo '{"tool":"zhihu_search_and_fetch","args":{"query":"AI Infra","max_items":5,"min_vote":0,"kinds":["answer","article"]}}' | \
  .venv/bin/python mcp_server.py --cli
```

`max_items` 是上限，筛选或抓取失败可能导致返回不足。垂直技术话题可先降低 `min_vote` 扩大候选，再由 Agent 阅读筛选；同时检查 `errors` 字段。

### 持续追踪多个话题

向 `zhihu_monitor_topics` 传入：

```json
{
  "topics": ["推理引擎", "GPU 调度", "分布式训练"],
  "max_items_per": 5,
  "min_vote": 30,
  "since_days": 7,
  "already_seen_ids": [],
  "topic_workers": 3,
  "fetch_workers": 2
}
```

Agent 读取 `by_topic` 下各话题的 `items`，生成摘要并保存 `all_seen_ids`，下次传入 `already_seen_ids`。调度和持久化由 Agent 或外部任务系统负责，MCP 本身不运行定时任务。

### 结合直接搜索与 AI 直答

直接搜索适合建立可核验的原文清单，直答可补充检索角度和来源线索。采用混合策略时，对两条路径的来源统一抓取原文、去重并评价。

**70% 直接搜索 + 30% 直答来源**可以作为候选配额的起点，但还没有实验证明它是最优比例。不要为了凑比例保留低质量或重复来源，也不要把直答生成的摘要直接当成原文证据。完整实测与方案分析见 [AI Infra 对比报告](docs/知乎直答与直接搜索对比实测-AIInfra-2026-09-09.md)。

<a id="docs"></a>

## 📚 实测与文档

| 文档 | 内容 |
| :--- | :--- |
| [Agent 集成指南](AGENTS.md) | 工具参数、返回结构、增量检索与错误处理 |
| [Codex 接入验证](docs/codex-integration-2026-9-9.md) | 经 Codex MCP 客户端完成的真实调用记录 |
| [直接搜索 vs. AI 直答](docs/知乎直答与直接搜索对比实测-AIInfra-2026-09-09.md) | AI Infra 资料搜集对比、引用核验及 70/30 混合策略分析 |
| [变更日志](docs/change-log-2026-9-9.md) | 工具、节流、Cookie 管理和公开仓库整理记录 |
| [维护约定](CLAUDE.md) | 依赖、代码风格与验证流程 |

实测记录反映当次网络、登录态和查询条件，耗时与返回数量会随任务变化。

## 🗂️ 项目结构

```text
zhihu-mcp/
├── mcp_server.py        # MCP / CLI 入口，注册 11 个工具
├── cookie_admin.py      # 本地 Cookie 管理页面
├── zhihu_main.py        # 知乎主站搜索客户端
├── zhida_client.py      # 知乎直答客户端与流式响应解析
├── fetch_zhihu.py       # 回答 / 文章正文抓取
├── zse.py               # 请求签名
├── requirements.txt    # MCP 运行依赖
├── AGENTS.md            # Agent 使用指南
├── CLAUDE.md            # 维护约定
└── docs/                # 接入记录、对比研究与变更日志
```

`probe.py`、`probe_modes.py`、`dump.py`、`pw_sniff.py`、`test_stream.py` 和 `captcha_solver.py` 是协议研究辅助脚本，正常使用 MCP 无需运行。部分脚本需要 Playwright 等额外依赖；调用直答的探测脚本也会消耗账号额度。

## 🛠️ 常见问题

| 情况 | 处理方式 |
| :--- | :--- |
| `401`、登录无效或 `ERR_TICKET_NOT_EXIST` | 在本地管理页更新 Cookie，再调用健康检查 |
| 无法导入 `mcp` / `FastMCP` | 确认客户端使用虚拟环境 Python，并重新安装 `requirements.txt` |
| 持续 `403` / `429` 或正文抓取失败 | 查看 `errors`，降低查询频率和并发，稍后重试 |
| MCP 启动或工具调用超时 | 检查网络和 Cookie；Codex 可按示例配置 30 秒启动、120 秒工具超时 |
| 内容为空或少于请求数量 | 检查筛选条件、原文是否可访问和抓取错误，不能保证每次凑满 |
| `8899` 端口被占用 | 单独启动管理页并换端口，或检查是否重复启动了管理服务 |

## 使用说明

这是社区项目，使用知乎网页接口与个人登录态，与知乎官方无隶属关系。适合技术学习与个人资料管理；请遵守平台规则和内容版权，避免大规模采集、商业转售或恶意请求。

Cookie 属于账号凭证。`cookie.txt`、Cookie 备份、抓包数据、本地运行状态和 `TROUBLESHOOTING.md` 均已设置为 Git 忽略项。提交 Issue 时请使用脱敏后的最小复现信息。

---

<div align="center">

**从检索到原文，让每一份摘要都有出处。**

[提交 Issue](https://github.com/we1005/zhihu-mcp/issues) · [查看源码](https://github.com/we1005/zhihu-mcp)

</div>