youdao-note-mcp

有道云笔记的 MCP 服务。本地以 stdio 暴露给 MCP 客户端（WorkBuddy / Claude Desktop 等）， 内部桥接到有道官方的 MCP over SSE 端点。

为什么是桥接，而不是直接对接

调研结论（2026-09 实测）：

官方端点本身就是 MCP，所以本项目不做协议转换，只做三件有价值的事：

1. 本地 stdio 化 —— 客户端配 stdio 最稳，不必直连远端 SSE；

2. 运行时动态发现工具 —— 上游工具是运行时拉取后透传的，官方改版/加工具不用改代码；

3. 可观测与容错 —— 鉴权、连接、调用失败都收敛成结构化中文提示，而不是抛一个看不懂的异常。

Related MCP server: SiYuan MCP Server

架构

MCP 客户端
   │  stdio (JSON-RPC)
   ▼
youdao_note_mcp.server        ← 元工具 + 透传路由
   │  MCP over SSE (x-api-key)
   ▼
open.mail.163.com/api/ynote/mcp/sse   ← 有道官方

暴露两类工具：

• 上游透传工具：运行时发现，名称/描述/入参 schema 与官方完全一致；

• 本地元工具（永远可用，即使没配 Key）：

  • yn_status —— 配置与连接体检，报错时先调它；

  • yn_list_tools —— 列出上游实际暴露的工具及其 schema；

  • yn_refresh_tools —— 刷新工具缓存。

安装

方式一：uvx 直接跑（推荐，无需安装）

uvx --from git+https://github.com/Lancenas/youdao-note-mcp.git youdao-note-mcp

方式二：pip 安装

pip install git+https://github.com/Lancenas/youdao-note-mcp.git
# 装完得到可执行命令 youdao-note-mcp

方式三：本地开发

git clone https://github.com/Lancenas/youdao-note-mcp.git
cd youdao-note-mcp
pip install -e .

获取 API Key

1. 打开 https://mopen.163.com/

2. 用手机号登录（前提：有道云笔记账号已绑定手机号）

3. 在「API 管理」中取 Key

Key 只能访问该账号自己的笔记，无法跨账号。

配置到 MCP 客户端

在 MCP 配置文件的 mcpServers 下加（以 WorkBuddy 为例： 侧边栏 插件 → 右上角 MCP 服务器 → 配置 MCP）：

用 uvx（无需先安装）：

{
  "youdao-note": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/Lancenas/youdao-note-mcp.git", "youdao-note-mcp"],
    "env": {
      "YOUDAONOTE_API_KEY": "你的Key"
    }
  }
}

已 pip 安装过则用更简单的形式：

{
  "youdao-note": {
    "command": "youdao-note-mcp",
    "env": {
      "YOUDAONOTE_API_KEY": "你的Key"
    }
  }
}

⚠️ Key 只填在你自己本机的配置里，不要提交到任何仓库。 .env 已在 .gitignore 中排除，.env.example 只含占位符。

环境变量说明见 .env.example。

使用

配置好并重启客户端后，直接用自然语言即可，无需记工具名：

• 「列出我有道云笔记根目录的内容」

• 「搜索我笔记里关于 MCP 的内容」

• 「帮我新建一篇笔记，标题《xxx》，内容是……」

出问题先让 AI 调 yn_status，它会一次性给出 Key 是否配置、上游是否连上、 工具数量、最近一次错误。

自测

python tests/smoke_test.py

用内置的手写 mock SSE 上游跑端到端，覆盖三个场景： A 有 Key 的完整链路（工具发现 + 透传调用）、B 无 Key 的降级、C 错误 Key 的鉴权失败。 当前 13 项检查全部通过。

真实环境验证（2026-09-21，已用真实 Key 打通）

• 工具发现：官方暴露 21 个工具，全部被动态发现并透传，入参 schema（含 required、 字段说明）完整保留 —— 这是选 low-level API 而非高层 add_tool() 才拿到的效果。

• 读：listNotes(parentId="0") 正常返回；getNoteTextContent 读回内容与写入逐字一致。

• 写：createNote → 读回校验 → deleteNote → searchNotes 复查剩余 0 条（不留垃圾）。

官方工具覆盖面：

已知约束

• ⚠️ deleteNote 是软删除，笔记会进有道云笔记回收站。删除后用 searchNotes / listNotes 复查会是 0 条，但用户在客户端的「回收站」里仍然看得到。 官方 MCP 未提供任何回收站相关工具（21 个工具里没有 trash / restore / purge）， 因此无法通过 MCP 彻底清除，需要用户在客户端手动清空回收站。 写自动化清理脚本时要如实说明这一点，别承诺"删干净了"。

• 实体名带后缀：listNotes 返回的笔记名自带 .note、.md 等后缀 （如 标题.note），按标题匹配时要考虑这一点。

• 上游偶发连接失败：实测出现过首次 listNotes 连接失败、第二次才成功的情况。 本实现对可重试失败自动重连重试一次，已覆盖该场景；连续两次失败才会报错。 另注：官方把鉴权失败也归在 connect 类型里（返回 401），看 last_error 里的 401 Unauthorized 即可区分。

• 无常驻连接：每个 tool call 都会重新走一次 SSE 握手。这是刻意的—— mcp 2.x 的 runner 给每个请求套了 anyio cancel scope，跨请求持有 SSE 连接会触发 Attempted to exit a cancel scope that isn't the current tasks's current cancel scope 并让整个 server 挂掉。工具列表本身有缓存，不受影响。

托管到云开发 / 上架腾讯云 MCP 市场

本项目是 stdio 形态，云端市场需要 HTTP 形态。腾讯云开发（CloudBase）提供 cloudbase-mcp-transformer，可把 stdio 转成远程 Streamable HTTP 并托管。

deploy/cloudbase/ 下已备好三个上架必需文件：

已实测（2026-09-21，真实 Key）：本地跑 transformer 转换后通过 http://127.0.0.1:3000/messages 连接，得到 24 个工具（21 上游 + 3 元工具）， yn_status 返回 api_key_configured: true —— 即容器环境变量能被 stdio 子进程继承， 使用者填的 Key 可正常透传。

部署与上架（需腾讯云账号，无法自动化）：

npm i -g @cloudbase/cli@latest
tcb login
cd deploy/cloudbase
tcb cloudrun deploy

注意：腾讯云 MCP 广场的上架申请目前仅面向企业级 MCP，个人开发者暂不开放； 云开发 MCP 市场无此限制。

许可

MIT © Lancenas