WizNote MCP Server（为知笔记私有服务器 MCP）

English version: README.en.md

把为知笔记私有部署（wiznote/wizserver）的 OpenAPI 封装成 MCP 服务，让支持 MCP 的 Agent （如 Hermes、Claude Desktop、Cursor 等）能直接搜索、读写笔记，并把网页（含微信公众号 文章 + 内嵌图片）一键收藏为笔记。

所有敏感配置（服务器地址、账号、密码、知识库 GUID）都放在 .env 里，绝不写进代码。

功能

网页收藏特性

• 普通文章/博客：用 readability 提取正文。

• 微信公众号文章（mp.weixin.qq.com）：用移动端 UA + Referer 绕过验证页，按 #activity-name / #js_name / #js_content 提取标题/作者/正文（无需无头浏览器）。

• 图片本地化：正文里的每张图片会下载并上传为笔记资源，<img> 改写为 index_files/<name>，网页端和 Android 客户端都能显示。

• 反爬/验证码：直接返回失败，不重试、不渲染。

Related MCP server: Zhihu-Collections-MCP

安装

git clone <your-repo> wiznote-mcp
cd wiznote-mcp
bash install.sh          # 建 .venv、装依赖、生成 .env（从 .env.example）

然后编辑 .env 填入真实信息：

vim .env

WIZNOTE_BASE_URL=https://wiznote.crapex.cc
WIZNOTE_USER_ID=you@your-domain.com     # 私有部署必须用完整邮箱
WIZNOTE_PASSWORD=your-password
WIZNOTE_KB_GUID=                         # 留空则登录时自动发现

也可以不生成 .venv，直接用系统 Python（需自行 pip install -r requirements.txt）， 或让 MCP 宿主直接注入这些环境变量（见下文 Hermes 配置）。

在 MCP 宿主中注册

服务通过 stdio 通信。把 command 指向本项目的 wiznote.sh（它会自动加载 .env）：

Hermes

hermes config set mcp_servers.wiznote.command "/abs/path/to/wiznote-mcp/wiznote.sh"
hermes config set mcp_servers.wiznote.args ""
hermes gateway restart

注意：args 必须留空字符串。Hermes 的 config set 会把列表存成字符串，导致 python 把整个 [...] 当成文件名（报 "Connection closed"）。用 wiznote.sh 包装脚本 当 command 即可规避。

通用（宿主直接注入环境变量）

若宿主支持 env 注入（如 Hermes 的 mcp_servers.wiznote.env），也可不依赖 .env， 由宿主传入 WIZNOTE_* 变量；本项目 server 会优先使用宿主注入的值。

验证

# 用官方 MCP 客户端做一次 stdio 握手 + 工具发现
python -m mcp client wiznote.sh     # 视宿主工具而定

或在 Hermes 中：

hermes mcp test wiznote

踩坑记录（实现要点）

1. 账号必须是完整邮箱（you@your-domain.com），纯用户名在私有部署下报密码错。

2. 搜索参数是 ss，不是 keyword/query：GET /ks/note/search/{kbGuid}?ss=...。

3. 笔记正文位置：create 返回在 result.html，但 download 把正文放在顶层 html/info，不在 result —— get_note 必须用返回完整响应体的接口。

4. 字符编码：抓取页面必须 r.content.decode("utf-8")（不能用 r.text 自动识别）， 且笔记 HTML 头部加 <meta charset="utf-8">，否则中文在网页端/Android 端变乱码。

5. 图片资源绑定：save 时 resources 字段必须传裸文件名（如 1786616855133-0cd）， 而不是 index_files/... 的 url —— 传 url 会被静默丢弃，Android 客户端只显示占位符。

6. 微信正文隐藏样式：#js_content 自带 visibility:hidden;opacity:0，需清洗掉， 否则网页端整块不可见。

许可证

MIT