语雀 MCP Server（本地版 · 双认证模式）

一个用 Python 编写的本地 MCP server，让 AI 客户端（ZCode）可以直接读写你的语雀文档。

认证方式（按优先级自动选择）

模式	环境变量	要求	接口
官方 OpenAPI	YUQUE_TOKEN	需超级会员	/api/v2/...
网页端 Cookie	YUQUE_COOKIE	免费，任何用户可用	/api/...（内部接口）

它能做什么（6 个工具）

工具	功能
get_user	获取当前账号信息（验证凭证是否有效）
list_repos	列出当前账号的知识库
list_docs	列出知识库里的文档
create_doc	创建文档（Markdown 正文）
get_doc	获取文档内容
update_doc	更新文档标题/正文

一、免费方式：获取 Cookie（不需要超级会员）

1. 用 Chrome/Edge 登录语雀网页版（https://www.yuque.com）
2. 按 F12 打开开发者工具 → 切到 Network（网络） 标签
3. 刷新页面，点击任意一个请求
4. 在右侧 Request Headers 里找到 Cookie: 开头的整段内容（很长的一串）
5. 整段复制（含 _yuque_session=... 和 yuque_ctoken=...）

⚠️ 一定包含 yuque_ctoken，它是写操作（创建/更新文档）要用的 CSRF 令牌。 Cookie 有效期约 2 周，过期后在 Settings → MCP 里重新粘贴即可。

二、把凭证填进 ZCode

ZCode → Settings → MCP → 找到 yuque → 在环境变量里粘贴：

• YUQUE_COOKIE：粘贴上一步复制的整段 Cookie 值（免费路线，推荐）

⚠️ Cookie 等于你的登录态，别贴到聊天框、别提交进 git、别发给任何人。

三、重启 ZCode

配置修改后重启 ZCode（新会话自动连接），在 Settings → MCP 确认 yuque 已连接。 之后说一句「把 XXX 写成语雀文档」即可。

手动验证（可选）

pip install "mcp>=1.2.0,<2"   # mcp 2.x 移除了 FastMCP，必须锁 1.x
python test_client.py          # 协议自测：握手 → 列工具 → 两种认证模式链路

文件说明

• server.py — MCP server 本体（双认证模式，@mcp.tool() 注册工具，stdio 传输）
• test_client.py — 模拟 MCP 客户端的自测脚本（3 组用例）
• requirements.txt — 依赖（mcp 1.x）

踩坑记录（学习笔记）

1. mcp 2.0.0 移除了 FastMCP：pip install mcp 默认装 2.x 会报 ModuleNotFoundError: No module named 'mcp.server.fastmcp'，必须锁 mcp>=1.2,<2。
2. Windows 下 spawn 进程要用绝对路径：command 填 python.exe 完整路径，别写 python。
3. 语雀 OpenAPI 令牌是超级会员专享（2022 年后的策略）：免费用户改用网页端内部接口
   • cookie 认证。实测可用的端点（cookie 模式）：
   • GET /api/mine（用户）、GET /api/mine/books（知识库）、 GET /api/docs/{slug}?book_id=...&mode=markdown（文档，正文在 sourcecode 字段）
   • 创建文档：POST /api/docs（JSON 体：book_id/title/format/body/body_draft/public）
   • 更新文档：PUT /api/docs/{id}/content 再 PUT /api/docs/{id}/publish（先写草稿后发布）
4. cookie 模式写操作三要素：yuque_ctoken 同时作为 cookie 和 X-CSRF-Token 请求头； 请求头必须带 X-Requested-With: XMLHttpRequest；请求体是 JSON（不是表单）， 且要带 Referer: https://www.yuque.com/{login}/{book_slug}。
5. 网页端接口是非公开的：语雀改版可能需要适配；这是社区方案（elog、 yuque-cookie-plugin 等）都在用的路线。第一次写 404 很正常——先抓真实源码， 别猜端点。