simplenote-mcp

simplenote-mcp

一个 MCP（Model Context Protocol）服务，让任何兼容 MCP 的 AI 工具都能访问你的 Simplenote 数据——默认只读；运行 simplenote-mcp setup 并启用写入模式后，还可选择启用写入工具（创建、更新、移入废纸篓、恢复、还原）。

在 macOS 上，它可以直接从本地 Simplenote 桌面应用的 Core Data 存储读取数据，完全离线，无需身份验证。在 Linux 和 Windows 上（以及未安装桌面应用的 macOS 上），它会在运行一次 simplenote-mcp setup 后，通过 Simperium HTTP API 通信。

兼容 Claude Desktop、Claude Code、Cursor、VS Code（Copilot）、Zed、Cline、Windsurf，以及任何其他支持 MCP 的客户端。

快速开始

运行一次设置：

npx -y @automattic/simplenote-mcp setup

在已安装并同步 Simplenote 桌面应用的 macOS 上，设置程序会检测本地数据库，并询问是否使用它。接受该选项后，即可完全离线、以只读方式使用。在 Linux、Windows 或未安装桌面应用的 macOS 上，设置程序会提示你输入 Simplenote 邮箱，发送身份验证代码，然后要求输入该代码并询问是否启用写入模式。

然后在 MCP 客户端中注册该服务。

Claude Code：

claude mcp add simplenote -- npx -y @automattic/simplenote-mcp

Codex：

codex mcp add simplenote -- npx -y @automattic/simplenote-mcp

对于 Claude Desktop、Cursor、VS Code、Zed、Cline 和 Windsurf，请参阅下方的配置——这些客户端需要通过编辑 JSON 文件进行配置，而不是使用 CLI 命令。

重启客户端，然后让它列出你的标签。

要求

• Node.js 22+
• 满足以下条件之一：
  • **macOS：**已安装并同步 Simplenote 桌面应用，或
  • 任何平台：拥有 Simplenote 账户（你需要运行一次 simplenote-mcp setup）

安装

大多数用户无需手动安装任何内容——MCP 配置中的 npx -y @automattic/simplenote-mcp 会在首次使用时完成安装。

如果你更倾向于全局安装（启动更快，首次使用时无需从冷缓存下载）：

npm install -g @automattic/simplenote-mcp

然后在 MCP 配置中直接将 simplenote-mcp 设为 command。

设置和身份验证

运行一次设置以创建 config.json。macOS 原生设置无需 Simplenote 身份验证；API 设置则需要。

一次性设置

npx -y @automattic/simplenote-mcp setup

如果检测到 macOS 本地 Simplenote 数据库，设置程序会提供使用该数据库的选项，并写入包含 source: "local" 的 config.json。

否则，设置程序会检查 auth.json 中是否已有令牌。如果已存储令牌，设置程序会重用该令牌，并只询问是否启用写入模式。如果未存储令牌，设置程序会提示你输入 Simplenote 邮箱，发送一封包含短身份验证代码的魔法链接邮件，提示你输入代码，然后询问是否启用写入模式。成功后，程序会写入 config.json，并将令牌以 0600 权限存储在 auth.json 中。

平台	路径
macOS	~/Library/Application Support/simplenote-mcp/auth.json
Linux	$XDG_CONFIG_HOME/simplenote-mcp/auth.json（默认为 ~/.config/simplenote-mcp/auth.json）
Windows	%APPDATA%\simplenote-mcp\auth.json

config.json 和 telemetry.json 与 auth.json 位于同一个 simplenote-mcp 配置目录中。

删除已存储的令牌：

npx -y @automattic/simplenote-mcp logout

无交互模式 / CI

直接导出令牌即可跳过 auth.json：

SIMPLENOTE_TOKEN=<token> npx -y @automattic/simplenote-mcp

此环境变量会绕过 auth.json。

SIMPLENOTE_TOKEN 不会绕过 config.json；服务仍需要配置文件，以确定是使用本地存储还是 API 提供方。对于无交互环境，请在上方列出的对应平台配置目录中创建 config.json：

{
  "source": "api",
  "writeMode": false
}

仅当你希望开放写入工具时，才将 writeMode 设为 true。

令牌有效期

Magic-link 令牌似乎会按用户保持不变（请求新代码通常会返回相同的令牌，除非服务器端使其失效）。正常使用时未观察到令牌过期；如果 Simperium API 返回 401，应视为“删除旧令牌并重新运行设置”。没有自动刷新机制——magic-link 身份验证需要用户交互。身份验证端点设有速率限制（反复失败会导致 IP 被封锁约 10 分钟），因此不要编写脚本反复尝试。

配置

带有 CLI 的客户端（Claude Code、Codex）可以通过一条命令注册服务——见下文。其他配置均采用 JSON：所有 MCP 客户端最终都使用相同的 { command, args, env } 结构，区别仅在于配置文件位置和顶层键（mcpServers、servers 或 context_servers）。

Claude Code

推荐：

claude mcp add simplenote -- npx -y @automattic/simplenote-mcp

或者编辑 ~/.claude.json / 项目中的 .mcp.json，使用与下文 Claude Desktop 相同的 JSON 结构。

Codex

推荐：

codex mcp add simplenote -- npx -y @automattic/simplenote-mcp

或者直接编辑 ~/.codex/config.toml：

[mcp_servers.simplenote]
command = "npx"
args = ["-y", "@automattic/simplenote-mcp"]

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

{
  "mcpServers": {
    "simplenote": {
      "command": "npx",
      "args": ["-y", "@automattic/simplenote-mcp"]
    }
  }
}

启动客户端前，先在终端中运行一次 npx -y @automattic/simplenote-mcp setup。

重启 Claude Desktop 以应用配置更改。Windows 特有的问题请参阅下文的 Windows 注意事项。

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）。JSON 结构与 Claude Desktop 相同。

VS Code（GitHub Copilot）

通过 命令面板 →“MCP: Open User Configuration” 配置用户设置，或使用项目中的 .vscode/mcp.json。注意：VS Code 使用顶层键 servers，而不是 mcpServers。

{
  "servers": {
    "simplenote": {
      "command": "npx",
      "args": ["-y", "@automattic/simplenote-mcp"]
    }
  }
}

Zed

在 Zed 的 settings.json 中：

{
  "context_servers": {
    "simplenote": {
      "command": {
        "path": "npx",
        "args": ["-y", "@automattic/simplenote-mcp"]
      }
    }
  }
}

Zed 使用不同的架构——通过嵌套的 command 对象配置 context_servers。

Cline

打开 Cline MCP Servers 面板 → 编辑 cline_mcp_settings.json。JSON 结构与 Claude Desktop 相同（顶层键为 mcpServers）。

Windsurf

~/.codeium/windsurf/mcp_config.json。JSON 结构与 Claude Desktop 相同。

自定义存储路径（macOS）

如果本地 Simplenote 数据不在默认路径下：

1. 打开 Finder，按 Cmd+Shift+G，粘贴 ~/Library/Group Containers/
2. 找到以 com.automattic.SimplenoteMac 开头的文件夹（通常带有类似 PZYM8XX95Q. 的前缀）
3. 导航至 Data/Simplenote.storedata

然后传入 --path：

{
  "mcpServers": {
    "simplenote": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/simplenote-mcp",
        "--path",
        "/path/to/Simplenote.storedata"
      ]
    }
  }
}

无论是否配置了令牌，--path 都会强制使用原生提供程序。

其他标志

• -h、--help — 打印用法信息并退出。
• -V、--version — 打印版本并退出。

未知标志和意外的位置参数都会被拒绝。这样可以避免忽略 --paht 之类的拼写错误，并回退到 config.json 中配置的提供程序，却不作提示。

遥测

Simplenote MCP 会向 Automattic 发送匿名使用事件。随机生成的 UUID 会存储在与 config.json 相同的配置目录中的 telemetry.json 里，并作为 _ui 发送，同时设置 _ut=simplenote:local_uuid。

所跟踪的事件仅限于设置选项（API 设置时的 type、操作系统系列、写入模式和身份验证方式）以及工具调用（tool、提供程序、成功或失败）。不会发送笔记 ID、笔记内容、标签、搜索查询、Simplenote 账户详情或令牌。

若要仅在本次运行中选择退出，请设置：

SIMPLENOTE_MCP_DISABLE_TELEMETRY=1 npx -y @automattic/simplenote-mcp

若要永久选择退出：

npx @automattic/simplenote-mcp disable-telemetry

从本地检出版本构建后运行时，也可以使用 node server.js disable-telemetry。

提供方解析

除非提供了 --path，否则服务器会从 config.json 中选择数据源：

1. --path <file> — 使用指定的存储文件强制启用 macOS 原生提供方
2. source: "local" — 使用默认的 macOS Simplenote 存储库，只读
3. source: "api" 加上 auth.json 或 SIMPLENOTE_TOKEN — 使用 Simperium API 提供方
4. 配置缺失或格式错误 — 退出并显示可执行的 simplenote-mcp setup 提示

运行 simplenote-mcp setup 可创建或替换配置。仅有令牌不足以选择 API 提供方。

可用工具

无论配置了哪个提供方，都可以使用基本读取工具。macOS 原生模式为本地只读模式。写入工具和版本历史工具需要使用 Simperium API 提供方；在当前服务器中，启用 API 写入模式后才会提供这些工具。

list_tags

列出 Simplenote 账户中的所有标签。

参数： 无

返回： 按索引排序的 {name, index} 数组

list_notes

列出最近的笔记，可按标签筛选。

参数：

• tag（字符串，可选）— 按标签名称筛选
• limit（数字，可选，默认值：20，最大值：100）— 返回的笔记数量上限
• include_deleted（布尔值，可选，默认值：false）— 包含已移至废纸篓的笔记

返回： 按置顶状态和修改日期排序的 {id, title, tags, pinned, modified, deleted} 数组

search_notes

按内容、标题或标签搜索笔记。

参数：

• query（字符串，必填）— 搜索词（不区分大小写）
• limit（数字，可选，默认值：10，最大值：100）— 结果数量上限
• include_deleted（布尔值，可选，默认值：false）— 包含已删除的笔记

返回： {id, title, tags, snippet, modified, deleted} 数组

get_note

获取指定笔记的完整内容。

参数：

• id（字符串，必填）— 笔记 ID（simperiumkey）
• include_deleted（布尔值，可选，默认值：false）— 允许获取已删除的笔记

返回： {id, content, tags, pinned, markdown, deleted, created, modified}

create_note

创建新笔记。写入工具 — 需要在 simplenote-mcp setup 中启用写入模式，并使用 Simperium API 提供方。

参数：

• content（字符串，必填）— 笔记内容（第一行将成为标题）
• tags（字符串数组，可选）— 要添加的标签
• markdown（布尔值，可选，默认值：true）— 启用 Markdown 渲染
• pinned（布尔值，可选，默认值：false）— 置顶

返回： {success, id, version, title}

update_note

更新现有笔记。写入工具 — 需要启用写入模式并使用 Simperium API 提供方。

重要： content 和 tags 会完整替换现有值。若只更改笔记的一部分，请先调用 get_note，再传入合并后的内容。传入部分内容会导致其余内容被删除。

参数：

• id（字符串，必填）— 笔记 ID
• content（字符串，可选）— 新的笔记内容
• tags（字符串数组，可选）— 替换标签列表（请提供完整列表）
• markdown（布尔值，可选）— 启用/禁用 Markdown 渲染
• pinned（布尔值，可选）— 置顶/取消置顶

必须至少提供 content、tags、markdown 或 pinned 中的一项。

返回： {success, id, version}

trash_note

软删除笔记（将其移至 Simplenote 废纸篓）。笔记仍保留在存储桶中，可从任何 Simplenote 客户端恢复。写入工具 — 需要启用写入模式并使用 Simperium API 提供方。

参数：

• id（字符串，必填）— 笔记 ID

返回： {success, id, title, trashed_at}

restore_note

恢复之前移至废纸篓的笔记，使其重新出现在活动列表中。与 trash_note 作用相反。写入工具 — 需要启用写入模式并使用 Simperium API 提供方。

参数：

• id（字符串，必填）— 笔记 ID

返回： {success, id, title, restored_at}

get_note_history

列出笔记的近期版本，并提供简短的内容预览。此操作为只读；当前服务需要启用写入模式的 Simperium API 提供程序。

参数：

• id（字符串，必填）— 笔记 ID
• limit（数字，可选，默认值：10，最大值：25）— 要返回的最大版本数

返回： {id, current_version, entries: [{version, modified_at, content_preview}]}，按当前版本优先排序。超出 Simperium 保留期限的版本会被静默丢弃；version 编号不连续表示存在缺失。

get_note_version

获取笔记某个指定历史版本的完整内容。此操作为只读；当前服务需要启用写入模式的 Simperium API 提供程序。在调用 revert_note 前，可用此工具预览内容。

参数：

• id（字符串，必填）— 笔记 ID
• version（数字，必填）— 版本号（正整数）

返回： {id, version, content, tags, pinned, markdown, deleted, created, modified}。如果该版本超出 Simperium 保留期限，则抛出 version_not_found。

revert_note

将笔记还原到之前的版本。此操作计入写入频率额度。此操作会绕过已移至废纸篓笔记的保护机制：还原到未移至废纸篓的版本会将笔记移出废纸篓；还原到已移至废纸篓的版本则会再次将笔记移入废纸篓。

建议流程：get_note_history → get_note_version（预览）→ revert_note。

参数：

• id（字符串，必填）— 笔记 ID
• version（数字，必填）— 要还原的目标版本（正整数）

返回： {success, id, reverted_from_version, new_version, no_op}。no_op: true 表示目标版本与当前版本相同，因此未执行写入，也未消耗频率额度。

需要在 simplenote-mcp setup 中启用写入模式。保留期限由 Simperium 决定，客户端无法配置。

使用示例

配置完成后，你可以向 AI 客户端提出类似这样的请求：

• “列出我的 Simplenote 标签”
• “显示我最近的笔记”
• “搜索我的笔记，查找 ‘recipe’”
• “显示带有 ‘ideas’ 标签的笔记”
• “获取笔记 [id] 的完整内容”
• “显示 [note title] 的版本历史”
• “显示那篇笔记的第 42 个版本是什么样的”
• “将那篇笔记还原到上一个版本”

写入工具（创建、更新、移至废纸篓、还原、回滚）默认关闭，且仅在使用 Simperium API 提供程序时可用。运行 simplenote-mcp setup 并选择启用这些工具。原生 macOS 数据会缓存在内存中，并在存储文件发生变化时刷新；Simperium API 响应会缓存 60 秒，如果 API 暂时不可用，则会回退到过期缓存。

Windows 注意事项

以下是一些值得了解的 Windows 特殊情况：

• 对于 Claude Desktop，请将 npx 包装在 cmd /c 中。否则，其子进程启动器有时无法在 PATH 中找到 npx.cmd：

  {
    "mcpServers": {
      "simplenote": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@automattic/simplenote-mcp"]
      }
    }
  }
  

• Claude Desktop 中的 %APPDATA% 展开在某些版本中可能会静默失败。如果服务无法找到其配置目录，请在 env 块中显式设置 APPDATA：

  "env": {
    "APPDATA": "C:\\Users\\<you>\\AppData\\Roaming"
  }
  

• JSON 中带反斜杠的路径必须转义（"C:\\Users\\..."）。也可以使用正斜杠（"C:/Users/..."），不容易出错。

故障排除

“未找到配置。运行 simplenote-mcp setup...” 启动 MCP 客户端前，先运行一次 npx -y @automattic/simplenote-mcp setup。

“未登录。运行 simplenote-mcp setup...” 你使用的是 Simperium API 路径，但没有令牌。在终端中运行 npx -y @automattic/simplenote-mcp setup。

“令牌已被拒绝。” 令牌可能已在服务器端失效。运行 npx -y @automattic/simplenote-mcp logout，然后运行 npx -y @automattic/simplenote-mcp setup。

工具列表为空 / “未找到 Simplenote 存储” 在 macOS 上，默认路径为 ~/Library/Group Containers/PZYM8XX95Q.com.automattic.SimplenoteMac/Data/Simplenote.storedata。如果你的存储位于其他位置，请传入 --path。如果你没有桌面应用，请运行 simplenote-mcp setup 切换到 API 路径。

首次调用工具非常慢 首次使用时，npx -y 会下载软件包。在网络较慢的情况下，这可能会超过 MCP 客户端的启动超时（约 10 秒）。你可以等待下载完成，或一次性进行全局安装：npm install -g @automattic/simplenote-mcp，然后将 "command": "npx" 改为 "command": "simplenote-mcp"（删除 args）。

Windows 上出现“command not found: npx”/“spawn npx ENOENT” 请参阅 Windows 说明中的 cmd /c 封装方式。

收不到设置邮件 检查垃圾邮件文件夹。身份验证端点设有速率限制——短时间内多次失败会导致 IP 被锁定约 10 分钟。请稍等片刻后重试。

一切看起来正常，但数据似乎过时 Simperium 响应会缓存 60 秒；原生 macOS 提供方会在存储文件的 mtime 发生变化时刷新。请等待一分钟，或重启 MCP 客户端以强制重新获取。

开发

源代码位于 src/，编译后的输出位于 dist/。

git clone https://github.com/Automattic/simplenote-mcp.git
cd simplenote-mcp
npm install          # installs deps + builds via `prepare`
npm test             # runs the test suite
npm run typecheck    # tsc --noEmit
npm run build        # tsc + chmod +x on the bin

使用 MCP Inspector 进行本地测试

MCP Inspector 为 MCP 服务提供浏览器界面——它会列出服务公开的工具、提示词和资源，让你使用任意参数调用它们，并打印通信双方的原始 JSON-RPC。当你想测试代码更改，又不想将服务接入真实客户端时，这个工具很有用。

针对本地构建运行：

npm run build
npm run inspect

打开它打印的 URL，然后点击 Connect。

直接从源代码运行，无需重新构建（迭代最快——使用 tsx）：

npx @modelcontextprotocol/inspector npx tsx src/server.ts

测试已发布的 npm 软件包（与用户实际获取的内容完全一致）：

npx @modelcontextprotocol/inspector npx -y @automattic/simplenote-mcp

显式选择提供方：

• 强制使用原生 macOS 提供方并指定自定义存储（覆盖配置）：

  npx @modelcontextprotocol/inspector node dist/server.js --path /path/to/Simplenote.storedata
  

• 使用 Simperium API 提供方——需要先运行 simplenote-mcp setup 并选择 API 模式，这会写入包含 source: 'api' 和 auth.json 令牌的配置。之后 Inspector 会自动选择 API 提供方。若要为本次会话使用其他令牌，请在启动 Inspector 前导出 SIMPLENOTE_TOKEN（覆盖 auth.json），或将令牌粘贴到 Inspector UI 的 Environment Variables 面板中。

Inspector 会通过 stdio 将服务作为子进程启动，因此任何可在真实 MCP 客户端配置中使用的设置在这里也都有效，包括 --path、环境变量和其他 Node 二进制文件。

在本地使用 Claude Code 测试

仓库中包含一个项目级 .mcp.json，用于将本地源码注册为名为 simplenote-dev 的服务。在仓库目录中打开 Claude Code 时，它会提示你启用该服务（由于此文件已提交，首次启用时会请求你的许可）。启用后，你在此目录中的 Claude Code 会话会通过 node --import tsx src/server.ts 调用正在开发的代码，无需构建。

工作流：

1. 运行 npm install 以安装 tsx；如果尚未运行过 simplenote-mcp setup，也请运行一次。开发服务会读取与常规安装相同的 config.json/auth.json。
2. 在仓库目录中打开 Claude Code，并在提示时批准 simplenote-dev。
3. 编辑 src/ 并保存，然后在 Claude Code 中运行 /mcp，重新连接 simplenote-dev 以应用更改。

项目级配置意味着开发服务只会在此目录中连接，不会影响你计算机上其他位置的 Claude Code 会话。

**注意：**如果 config.json 中的 writeMode: true，开发服务会修改你真实的 Simplenote 笔记——开发数据与生产数据之间没有隔离。迭代开发时，请使用禁用写入模式的设置，或使用专门用于测试的 Simplenote 账户。

仓库根目录中的 server.js 是一个轻量封装，用于导入 dist/server.js。它保持稳定，以便那些在 npm 包发布前就已配置为指向本地克隆的用户继续使用。

许可证

MIT