印象笔记（Yinxiang）连接器 · 跨平台能力包

把你的印象笔记变成 AI 客户端的"读写外脑"：既能检索已有笔记，又能把产出回写为原生 Markdown 笔记（客户端可切源码/预览），还能把整个文件夹批量备份成笔记（.md 独立成篇、其他文件作附件、图片内联）。

• 国内版 app.yinxiang.com，基于 zibuyu_evernote（Python 3 版 Evernote EDAM SDK）+ FastMCP。

• Windows / macOS 通吃，WorkBuddy / Trae / 任意支持 stdio MCP 的客户端通吃。

第一步：确认你的账户级别

印象笔记不同账户的单条笔记大小上限和每月上传流量不同，这会直接影响备份脚本的分批方式。请先确认自己属于哪一档：

数据来源：印象笔记帮助中心「我应该选用哪种印象笔记帐户类型?」（https://help.yinxiang.com/hc/articles/63016）。若官网后续调整，以官网为准。 不知道怎么查：打开印象笔记客户端 → 账户/设置 → 查看当前会员等级。备份脚本默认按最保守的 free 处理，付费用户建议显式加 --plan。

Related MCP server: Evernote MCP Server

第二步：生成 API Key（Developer Token）

印象笔记用 Developer Token 做第三方认证（国内版）：

1. 浏览器登录网页版：https://app.yinxiang.com

2. 手动访问下面这个地址（它不在任何菜单里，需要直接在地址栏输入）：

   https://app.yinxiang.com/api/DeveloperToken.action

3. 点击页面上的 "Create a developer token" 按钮。

4. 页面会生成一串以 S= 开头的长字符串，例如 S=s0:U=1234567:E=0123456789a:C=0123456789b:P=1cd:A=en-devtoken:V=2:H=00000000000000000000000000000000。 复制并妥善保存——⚠️ 它只显示一次。

5. 如果上面的页面打不开或找不到入口，改用印象笔记为 AI 对接提供的授权页：

   https://app.yinxiang.com/third/skills-oauth/

   登录后点授权，同样可拿到 Token。

🔒 安全提醒：Developer Token 等同于你整个印象笔记账户的钥匙，谁拿到谁就能读写。不要提交到 Git 仓库、不要放进公开同步盘、不要发到群里。若怀疑泄露，回到上面的页面撤销并重新生成。

第三步：准备 Python 环境

需要 Python 3.10+。推荐建独立 venv（避免污染系统环境）：

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

记下 venv 里 python 可执行文件的绝对路径，第四步要用：

• macOS：<包目录>/.venv/bin/python

• Windows：<包目录>\.venv\Scripts\python.exe

第四步：把 API Key 放进配置文件

编辑（不存在就新建）你客户端的主配置文件 mcp.json，加入 yinxiang 这一段：

{
  "mcpServers": {
    "yinxiang": {
      "command": "/绝对路径/.venv/bin/python",
      "args": ["/绝对路径/yinxiang-connector/server.py"],
      "env": {
        "EVERNOTE_TOKEN": "S=你的DeveloperToken",
        "YINXIANG_CHINA": "true",
        "YINXIANG_DEFAULT_NOTEBOOK": "我的笔记"
      }
    }
  }
}

说明：

• command 用 venv 里的 python（这样 mcp 等依赖才找得到）。

• args 指向本包的 server.py 绝对路径。

• EVERNOTE_TOKEN 填第二步拿到的 Token。

• YINXIANG_DEFAULT_NOTEBOOK 是默认写入的笔记本名（可留空 = 账户默认笔记本）。调用工具时也可用 notebook_name 参数临时指定，优先级更高。

配置文件位置：

• WorkBuddy：~/.workbuddy/mcp.json（Windows：C:\Users\<你>\.workbuddy\mcp.json）

• Trae（macOS）：~/Library/Application Support/Trae/User/settings/mcp.json（CN 版路径含 Trae CN）

• Trae（Windows）：%APPDATA%\Trae\User\settings\mcp.json

第五步：在 WorkBuddy/Trae 里连接（关键按钮）

1. 保存好 mcp.json 后，重启 WorkBuddy/Trae。

2. 打开连接器管理页面。

3. 点击页面右上角的「自定义连接器」。

4. 在列表里找到 yinxiang，点 信任 / 启用。

5. 新开一个会话，直接说："列出我的印象笔记笔记本"——能返回笔记本列表就说明接入成功。

之后就可用自然语言读写印象笔记了：

• "在印象笔记里搜'种植贷风控'"

• "把这份分析存进印象笔记，标题'现金流分析'，笔记本'我的笔记'"

第六步：在 Trae 里连接

Trae 同样支持 stdio MCP，配置字段与上面完全一致（command + args + env）。

1. 打开 Trae 设置 → MCP → 添加 → 手动添加；

2. 把第四步那段 JSON 粘进输入框，确认；

3. 重启 Trae，即可调用 yinxiang_* 四个工具。

4. 也可以放到项目级 .trae/mcp.json（跟项目走，适合多项目隔离）。

批量备份脚本 yinxiang_backup.py 是独立 Python 脚本，在 Trae 的终端里直接跑即可，无需经过 MCP。

四个 MCP 工具

批量备份文件夹

# 1) 先扫描看计划（dry-run，不需要 Token）
.venv/bin/python yinxiang_backup.py --workspace /路径/到/文件夹 --plan professional

# 2) 执行（同名笔记自动跳过，幂等）
.venv/bin/python yinxiang_backup.py --workspace /路径/到/文件夹 --plan professional --run

# 3) 清掉上次清单重跑
.venv/bin/python yinxiang_backup.py --workspace /路径/到/文件夹 --plan professional --reset --run

备份规则：

• .md → 每文件独立成一条原生 Markdown 笔记（客户端可查看/编辑源码，相对路径作标题）；

• 其他文件 → 按扩展名分组、组内按账户体积上限自动分批，文件作为附件贴在一条**「超级笔记」**里（可点击下载）；

• 图片 → 合并为一条内联笔记；

• .py / .rar 默认跳过；.git / .venv 等隐藏目录自动排除。

常见问题

Q：笔记写进去了，但附件只有一个文件名列表、点不开？ A：附件必须被正文用 <en-media> 引用才会显示。本包已修复并内置回读核验（跑完会打印 资源=N en-media=N），正常情况不会出现。

Q：客户端里找不到 Markdown 源码视图？ A：.md 备份用的是原生 Markdown 笔记（contentClass=yinxiang.markdown，源码藏在正文隐藏的 <center> 里），在客户端里可切换「编辑 / 预览」。如果看不到，说明该条不是这种格式——重新用本包脚本备份一次即可。

Q：上传报错 errorCode=11？ A：多为 ENML 属性不合法（如 class / id）或 XML 未转义。本包已内置属性白名单与转义处理。

Q：报 429 / 限流？ A：印象笔记对 API 调用频次有限制，脚本已带指数退避重试；间隔太短可适当放慢。

Q：能免费账户用吗？ A：可以，但单条笔记仅 25MB、每月上传流量 60MB。脚本默认即按 free 保守处理。

Q：Token 放哪里最安全？ A：放 mcp.json 的 env 或系统环境变量即可，不要放进被同步/被提交的目录。