Skip to main content
Glama
Lancenas

youdao-note-mcp

by Lancenas
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

youdao-note-mcp

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

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

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

路径

现状

有道云笔记 旧版 OpenAPI（OAuth 1.0/2.0 申请 ConsumerKey）

已停止新增申请，官网顶部明示，只能走邮件申请商务合作

官方 MCP 端点 https://open.mail.163.com/api/ynote/mcp/sse

✅ 在役。无 Key 访问返回 401 {"error":10002,"desc":"authentication failed"}

API Key 来源

https://mopen.163.com/ （网易智能开发者平台）→ 手机号登录 → API 管理

官方端点本身就是 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 条（不留垃圾）。

官方工具覆盖面：

类别

工具

笔记 CRUD

createNote renameNote moveNote deleteNote createDir createAnyNote

内容读写

getNoteTextContent updateMarkdownNote

检索

listNotes searchNotes

收藏

getRecentFavoriteNotes

待办

listTodos createTodo updateTodo deleteTodo listTodoGroups createTodoGroup updateTodoGroup deleteTodoGroup

剪藏

clipWebPage clipperSaveWithImages

已知约束

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

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

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

  • ⚠️ 用 uvx 启动时，首次可能因构建超时被 MCP 客户端判为连接失败。 实测（2026-09-21，macOS）：uvx --from git+https://... youdao-note-mcp 首次需 clone + 构建隔离环境，3 分半仍未完成握手，客户端报 Connection closed。 此外 uvx 常装在 ~/.local/bin 或 /opt/homebrew/bin，GUI 拉起的 MCP 子进程往往 不含这些目录，直接写 command: "uvx" 会报 spawn uvx ENOENT。 建议改用绝对路径：先 pip install .，再把 command 写成 console script 的绝对路径 （如 .../bin/youdao-note-mcp），实测冷启动 0.6 秒。

  • 无常驻连接：每个 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/ 下已备好三个上架必需文件：

文件

作用

Dockerfile

安装本服务 + transformer，CMD 执行 stdio → Streamable HTTP 转换

mcp-meta.json

市场元数据。其中 env_params 声明 YOUDAONOTE_API_KEY，由使用者在连接时填自己的 Key（不是打包进镜像）

DOC.md

市场展示文档（功能清单 + 环境变量说明）

已实测（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

Available Tools

3 tools
yn_list_toolsA

列出有道云笔记上游 MCP 实际暴露的所有工具及其入参 schema。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the behavioral burden. It conveys that the tool queries the actual upstream MCP state ('实际暴露的'), implying a live enumeration rather than a static list, which is useful. However, it doesn't disclose potential network/upstream dependency, failure behavior, or whether the list reflects already-refreshed tools versus triggering a fresh query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, complete sentence that front-loads the verb and resource with zero filler. Every word earns its place, and the parenthetical-free structure is easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter discovery tool, the description adequately covers the return content (tool names and input schemas). There is no output schema, but the description states what the tool returns. Minor omissions like output format or behavior when the upstream is unreachable are acceptable given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is nothing for the description to explain about inputs; the baseline of 4 applies. The mention of '入参 schema' refers to the return payload, not to this tool's own parameters, so it doesn't add or need parameter-level semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('列出') and resource ('上游 MCP 实际暴露的所有工具及其入参 schema'), making the tool's purpose immediately clear. It differentiates from siblings only implicitly — listing tools is naturally distinct from checking status (yn_status) or refreshing the tool list (yn_refresh_tools) — but it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to call this tool, when not to, or how it relates to the sibling tools yn_status and yn_refresh_tools. An agent must infer that this is a discovery/introspection tool from the description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

yn_refresh_toolsA

强制刷新上游工具列表缓存（上游改版或工具数量不对时使用）。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

没有提供 annotations，描述承担行为披露任务。“强制刷新缓存”说明了操作对象和强制属性，但没有披露潜在副作用（例如刷新期间列表工具是否不可用、是否会触发上游网络调用或限流）。虽然比泛化的“更新”更具体，但对无 annotation 的工具仍有缺口。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

单句描述，信息密度高；“强制刷新”和具体使用场景都放在前面，没有冗余或重复 schema 的内容。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

该工具零参数、无输出 schema，复杂度极低。描述已经覆盖调用所需的核心信息：动作、目标、何时使用，足以让代理正确决定并调用。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

输入 schema 为空、参数为 0，因此按规则以 4 为基线。描述无需补充参数说明，也没有因 schema 覆盖不足而需要补偿的问题。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确列出动词“刷新”和宾语“上游工具列表缓存”，准确说明该工具做什么。与兄弟工具 yn_list_tools（列表）和 yn_status（状态）在名称和语义上有明显区分，不需要打开 schema 就能判断用途。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述给出明确使用时机：“上游改版或工具数量不对时使用”，这为 AI 提供了调用该工具的清晰触发条件。但它没有显式说明与 yn_list_tools/yn_status 的选用边界，例如“仅查看时用列表工具”，因此未达到满分。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

yn_statusA

检查有道云笔记 MCP 的配置与连接状态：返回 API Key 是否已配置、上游端点地址、连接是否就绪、上游工具数量。当笔记类工具报错时，先调用它判断是鉴权问题还是连接问题。

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

由于没有 annotations，描述承担了行为透明度的全部责任。它说明了工具是只读的状态检查，并披露了返回内容涉及鉴权、连接和上游工具数量，让 agent 能预期调用结果。但未说明该检查是否发起网络请求，略有保留，不过对诊断型工具已足够。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

一句话同时包含工具功能、返回内容和使用场景，信息密度高且没有冗余。前段描述状态检查，后段给出诊断触发条件，结构紧凑高效。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

对于零参数、无输出 schema 的状态检查工具，描述已列出关键输出维度（API Key 配置、端点、连接状态、工具数量），足以让 agent 正确理解和调用。没有缺失的关键信息。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

工具无参数，且 schema 覆盖率为 100%，因此参数语义不是负担。描述没有引入参数相关细节，这符合零参数工具的基线评分。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确说明了工具的功能（检查配置与连接状态）以及返回的核心信息（API Key 是否配置、端点、连接就绪状态、工具数量），与兄弟工具 yn_list_tools、yn_refresh_tools 的用途有明显区分。动词和资源清晰，不存在歧义。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述明确给出了使用时机：当笔记类工具报错时，先调用此工具判断是鉴权问题还是连接问题。虽然没有显式列出何时不使用或对比兄弟工具，但已提供清晰的诊断场景，足以引导 agent 在合适时调用。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedyn_list_tools
    • First observedyn_refresh_tools
    • First observedyn_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

每个工具都有明确且不重叠的职责：状态检查、列出工具、刷新工具缓存。工具间边界清晰，不会产生误选。

Naming Consistency5/5

所有工具使用统一的 yn_ 前缀加动词命名（status, list_tools, refresh_tools），风格一致，易于预测。

Tool Count5/5

作为管理MCP适配器，3个工具恰好覆盖状态、列举和刷新三个核心操作，没有冗余，也没有明显缺失。

Completeness4/5

适配器层面功能完整，但未提供直接的笔记操作工具（如增删改查），不过这可能是因上游工具由其他工具暴露，此处属于元管理范畴，因此仅扣一分。

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP SSE Proxy

    gomarble-ai
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Bridges STDIO-based MCP clients with SSE-based MCP servers, allowing applications like Claude Desktop to connect to remote MCP servers that use SSE transport.
    9
    -

  • SiYuan MCP Server

    jjdunlop
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that enables AI assistants like Claude and Cursor to interact seamlessly with SiYuan Note through 15 specialized tools. It supports comprehensive note operations including unified search, document management, daily notes, and tag manipulation.
    42 npm
    Apache 2.0

  • Obsidi MCP

    cameronsjo
    F
    license
    Not graded
    quality
    C
    maintenance
    Exposes Obsidian vault tools via Model Context Protocol (MCP) server over stdio, HTTP, or SSE transports, enabling AI assistants to read, write, search, and manage vault notes with 28+ built-in tools and CLI bridge integration.
    1
    -

  • siyuan-ai-mcp-bridge

    appdev
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides a local MCP stdio server that enables AI clients to read, search, create, update, and delete notes in SiYuan through its Kernel HTTP API, with configurable notebook and tool permissions.
    MIT