zhihu-mcp

以读为主的知乎 MCP 服务器（stdio），统一读取：

• 知乎想法：https://www.zhihu.com/pin/{id}
• 专栏文章：https://zhuanlan.zhihu.com/p/{id}
• 一级评论（分页）、楼中楼回复（分页）
• 作者、正文、发布时间、赞数、评论数等元信息

兼容 Claude Code CLI 与 Codex CLI。不含点赞/关注等社交写操作；仅有的两个写工具是回答草稿/编辑（zhihu_draft_answer、zhihu_edit_answer），默认只存草稿或只预览，且受独立限频保护（间隔 ≥60s、每小时 ≤3 次），详见下方工具表。

工作原理

• Playwright 管理一个独立持久化浏览器目录（默认 ~/.zhihu-mcp/browser-profile），不读取、不影响你日常浏览器的 Cookie。
• 默认使用系统 Chrome（channel: "chrome"，指纹更真实），失败时回退 Playwright 内置 Chromium。
• 数据获取分层：
  1. 在已登录页面环境内同源调用知乎接口（评论、想法正文）；
  2. 接口失效/触发校验时，导航到内容页解析内嵌的 js-initialData JSON（文章正文的主路径，因 /api/v4/articles 有浏览器签名校验）；
  3. 最后回退 DOM 选择器解析。
• 评论接口的签名校验是间歇性的（实测同一请求时而 200 时而 10003）：先自动重试； 一级评论在重试仍失败时会导航到内容页，拦截页面自身发出的带签名请求作为终极回退。
• 内置限速：相邻请求 ≥1.5s（含抖动）、每分钟 ≤20 次，可用环境变量调整。
• Cookie 安全：登录态只存在本地浏览器目录；不经由 MCP 返回、不写日志、.gitignore 已排除。

安装

cd ZhihuMCP
npm install
npm run build
# 若本机没有 Chrome，需要装内置浏览器：
# npx playwright install chromium

登录（首次使用）

推荐在终端登录（不受 MCP 工具超时限制）：

npm run login

会弹出浏览器窗口，用知乎 App 扫码即可，完成后窗口自动关闭。也可以在对话里调用 zhihu_login 工具（需保证客户端工具超时 ≥3 分钟）。

登录过期时，任何工具会返回 NOT_LOGGED_IN 错误并提示重新登录。

接入 Claude Code CLI

方式一（命令行注册，作用于当前项目）：

claude mcp add zhihu -- node /绝对路径/ZhihuMCP/dist/index.js
# 全局可用：claude mcp add --scope user zhihu -- node /绝对路径/ZhihuMCP/dist/index.js

方式二（项目 .mcp.json）：

{
  "mcpServers": {
    "zhihu": {
      "command": "node",
      "args": ["/绝对路径/ZhihuMCP/dist/index.js"]
    }
  }
}

如需在对话内使用 zhihu_login（等待扫码约 1-3 分钟），启动时调大工具超时：

MCP_TOOL_TIMEOUT=300000 claude

接入 Codex CLI

~/.codex/config.toml 增加：

[mcp_servers.zhihu]
command = "node"
args = ["/绝对路径/ZhihuMCP/dist/index.js"]
# 如需在对话内扫码登录，调大工具超时（秒）：
tool_timeout_sec = 300

或使用命令行（较新版本）：

codex mcp add zhihu -- node /绝对路径/ZhihuMCP/dist/index.js

MCP 工具

工具	参数	说明
zhihu_login	无	打开浏览器窗口扫码登录
zhihu_check_login	无	返回 logged_in 与用户名
zhihu_get_content	url	读取想法/文章正文与元信息
zhihu_list_comments	url, cursor?, limit?(≤20)	分页读取一级评论
zhihu_list_replies	comment_id, cursor?, limit?(≤20)	分页读取楼中楼回复
zhihu_list_followees	url_token?, cursor?, limit?(≤20)	分页读取「关注的人」，省略 url_token 查当前登录用户
zhihu_draft_answer	question_url, text, publish?	写操作：把纯文本写入问题的回答，默认仅存草稿
zhihu_edit_answer	answer_url, text, mode?, confirm?	写操作：编辑已发布回答，默认只预览、需 confirm=true 才改

写操作：zhihu_draft_answer（默认存草稿）

这是唯一的写工具，用于给知乎问题回答。与读工具不同，它会改变账号状态，因此有额外护栏：

• 默认只存草稿（publish 省略或为 false）：通过页面自动化把文本写入回答编辑器，触发知乎自动保存，不点发布。你需要在网页端/App「创作中心 → 草稿箱」或问题页检查后手动发布。publish: true 才会直接发布。
• 不逆向签名：全程走页面自身的编辑器与请求（与真人操作同路径），不构造写接口签名、不对抗验证码。
• 防覆盖：若该问题已有未发布草稿，或你已回答过该问题，工具会拒绝写入并报错，不会覆盖已有内容。
• 独立严格限频：默认写操作间隔 ≥60s、每小时 ≤3 次（超限直接报 RATE_LIMITED，不排队）。自动化发布比阅读更易触发风控，强烈建议低频、草稿优先、人工过目后再发。
• 格式：文本按换行分段写入，暂不渲染 Markdown（标题/加粗/列表会作为纯文本）。
• 返回 mode（draft/published）、answer_url（发布时）、question_title、chars。

命令行用法（读文本文件存草稿）：

node scripts/draft.mjs "https://www.zhihu.com/question/123456" answer.txt            # 存草稿
node scripts/draft.mjs "https://www.zhihu.com/question/123456" answer.txt --publish  # 直接发布（谨慎）

写操作：zhihu_edit_answer（编辑已发布回答，两步确认）

编辑已发布的回答会改动线上公开内容，风险高于草稿，因此护栏更重：

• 默认只预览（confirm 省略或 false）：进入编辑器读取并返回当前线上内容和字数，不做任何修改、不消耗写配额。核对后带 confirm: true 才真正修改并点「提交修改」。
• 两种模式：mode: "append"（默认）在原回答末尾追加，保留原文与图片；mode: "replace" 整篇替换——注意写入的是纯文本，原回答的图片/加粗/列表等富文本会丢失。
• 改前自动本地备份：覆盖前把原文存到 ~/.zhihu-mcp/backups/answer-{id}-{时间}.txt，改坏可找回。
• 只能编辑本人发布的回答（否则页面无「修改」入口，会报错）。
• 同样走写操作限频。

命令行用法：

node scripts/edit.mjs "https://www.zhihu.com/answer/123" update.txt              # 预览当前内容（不改）
node scripts/edit.mjs "https://www.zhihu.com/answer/123" update.txt --confirm    # 末尾追加并提交
node scripts/edit.mjs "https://www.zhihu.com/answer/123" full.txt --replace --confirm  # 整篇替换并提交

统一返回结构

zhihu_get_content：

{
  "ok": true,
  "content_type": "pin | article",
  "id": "…",
  "url": "…",
  "title": "文章标题（想法为 null）",
  "body": "正文纯文本",
  "images": ["…"],
  "author": { "id": "…", "url_token": "…", "name": "…", "headline": "…", "avatar_url": "…" },
  "published_at": "ISO8601",
  "updated_at": "ISO8601",
  "vote_count": 0,
  "comment_count": 0,
  "source": "api | initial_data | dom"
}

zhihu_list_comments / zhihu_list_replies：

{
  "ok": true,
  "comments": [
    {
      "id": "…",
      "content": "评论纯文本",
      "author": { "…": "…" },
      "created_at": "ISO8601",
      "like_count": 0,
      "reply_count": 3,
      "reply_to_author": { "…": "被回复者（楼中楼）" },
      "is_author": true
    }
  ],
  "next_cursor": "下一页游标，null 表示无",
  "has_more": true,
  "total": 42
}

zhihu_list_followees：

{
  "ok": true,
  "url_token": "被查询用户",
  "users": [
    {
      "id": "…", "url_token": "…", "name": "…", "headline": "…",
      "avatar_url": "…", "follower_count": 0, "answer_count": 0, "articles_count": 0
    }
  ],
  "next_cursor": "5",
  "has_more": true,
  "total": 10
}

翻页：首页不传 cursor；之后把上一页的 next_cursor 原样传入，直到 has_more=false。

错误返回

{ "ok": false, "error": "NOT_LOGGED_IN", "message": "…", "hint": "…" }

错误码	含义
NOT_LOGGED_IN	未登录或登录过期，需 zhihu_login / npm run login
ANTI_CRAWLER	触发知乎风控校验，降低频率稍后重试；可 ZHIHU_MCP_HEADFUL=1 手动过校验
NOT_FOUND	内容不存在或已删除
RATE_LIMITED	请求过于频繁
INVALID_URL / INVALID_PARAM	链接或参数不合法
PARSE_ERROR	接口与 DOM 解析均失败（页面结构可能已变化）
BROWSER_ERROR	浏览器无法启动
LOGIN_TIMEOUT	扫码等待超时或窗口被关闭

环境变量

变量	默认值	说明
ZHIHU_MCP_PROFILE_DIR	~/.zhihu-mcp/browser-profile	浏览器持久化目录
ZHIHU_MCP_BROWSER_CHANNEL	chrome	浏览器 channel，失败回退内置 Chromium
ZHIHU_MCP_HEADFUL	0	置 1 始终有头运行（便于手动过风控）
ZHIHU_MCP_MIN_INTERVAL_MS	1500	相邻请求最小间隔
ZHIHU_MCP_MAX_PER_MINUTE	20	每分钟最大请求数
ZHIHU_MCP_LOGIN_TIMEOUT_MS	180000	扫码等待超时
ZHIHU_MCP_NAV_TIMEOUT_MS	30000	页面导航超时
ZHIHU_MCP_WRITE_MIN_INTERVAL_MS	60000	写操作最小间隔
ZHIHU_MCP_WRITE_MAX_PER_HOUR	3	写操作每小时上限

测试

npm test             # 单元测试（URL 解析、HTML 转文本、评论映射、错误分类）
npm run smoke        # 冒烟：拉起 MCP 服务器，列工具、查登录态
npm run acceptance   # 端到端验收（需已登录）：想法/文章正文、评论分页、楼中楼、错误分类

验收说明：计划中的首个验收用例 pin/2060006380807968738 实测已被知乎删除 （接口 404、桌面页回落到首页信息流、评论区关闭仅残留计数 451），服务器对其正确返回 NOT_FOUND；验收脚本因此改用存活想法验证完整读取链路，并保留该链接验证错误分类。

已知限制

• 想法评论区被关闭/内容被删时，知乎接口会返回空数据但 is_end 恒为 false； 本服务器会终止翻页（has_more=false）并透出 notice（如「评论区已关闭」）。
• 楼中楼回复在知乎持续强制签名校验时只有重试兜底（一级评论有页面拦截回退）。
• zhihu_draft_answer 依赖问题页的回答编辑器 DOM；知乎改版可能需要更新按钮/编辑器选择器。文本不渲染 Markdown。
• 尚无「读取回答正文」工具（问题正文/回答阅读目前未做成工具，可按需扩展 question/answer 适配器，无需改现有工具接口）。
• 不做验证码绕过与风控对抗；触发校验时需人工在有头浏览器中处理。
• zhihu_login 需要图形界面；纯远程/无头环境请先在本地登录后同步 ~/.zhihu-mcp 目录（注意其中含登录凭据，请勿提交仓库或外传）。