Simplenote MCP

simplenote mcp

MCP（模型上下文协议）服务器，允许任何兼容MCP的AI工具访问您的 Simplenote 数据——默认情况下读取，运行时使用选择写入工具（创建、更新、回收、还原、还原） simplenote-mcp setup 启用写入模式。

在macOS上，它可以直接从本地Simplenote桌面应用程序的核心数据存储中读取数据——完全离线，无需身份验证。在Linux和Windows（以及没有桌面应用程序的macOS）上，它在一次性使用Simperium HTTP API后与之对话 simplenote-mcp setup.

适用于Claude Desktop、Claude Code、Cursor、VS Code（Copilot）、Zed、Cline、Windsurf以及任何其他讲MCP的东西。

快速启动

运行安装程序一次：

npx -y @automattic/simplenote-mcp setup

在macOS上使用 Simplenote桌面应用程序 安装并同步后，安装程序会检测本地数据库并询问是否使用它。接受该选项是完全脱机和只读的。在没有桌面应用程序的Linux、Windows或macOS上，安装程序会提示您发送Simplenote电子邮件，发送身份验证代码，然后询问代码以及是否启用写入模式。

然后向您的MCP客户端注册服务器。

克劳德代码：

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

食品法典：

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 一次）

安装

大多数用户不需要手动安装任何东西-- npx -y @automattic/simplenote-mcp 在MCP配置中，首次使用时会执行此操作。

如果您更喜欢全局安装（启动速度更快，首次使用时无需下载冷缓存）：

npm install -g @automattic/simplenote-mcp

然后参考 simplenote-mcp 直接作为 command 在您的MCP配置中。

设置和身份验证

运行安装程序一次以创建 config.jsonmacOS原生设置不需要Simplenote身份验证；API安装程序会。

一次性设置

npx -y @automattic/simplenote-mcp setup

如果检测到本地macOS Simplenote数据库，安装程序将提供使用它并写入 config.json 和 source: "local".

否则，安装程序将检查中的现有令牌 auth.json。如果已经存储了一个，安装程序会重用它，只询问是否启用写入模式。如果没有存储令牌，安装程序会提示您发送Simplenote电子邮件，发送一封包含简短身份验证代码的魔术链接电子邮件，提示输入代码，然后询问是否启用写入模式。关于成功，它写道 config.json 并使用mode存储令牌 0600 在 auth.json.

config.json 和 telemetry.json 生活在同一个地方 simplenote-mcp config目录。

要删除存储的令牌，请执行以下操作：

npx -y @automattic/simplenote-mcp logout

无头/CI

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

SIMPLENOTE_TOKEN= npx -y @automattic/simplenote-mcp

env var绕过 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 vs。 servers vs。 context_servers)他们之间存在差异。

克劳德代码

推荐：

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

或编辑 ~/.claude.json /项目 .mcp.json 与下面的Claude Desktop具有相同的JSON形状。

法典

推荐：

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

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

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

克劳德桌面版

~/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/mcp.json （全球）或 .cursor/mcp.json （每个项目）。JSON格式与Claude Desktop相同。

VS代码（GitHub副本）

用户配置通过 命令面板→ “MCP：打开用户配置”，或每个项目 .vscode/mcp.json.注意：VS代码使用 servers 在顶层，不是 mcpServers.

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

泽德

在Zed的 settings.json:

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

Zed使用了不同的模式-- context_servers 带有嵌套 command 对象。

克莱恩

打开临床MCP服务器面板→ edit cline_mcp_settings.jsonJSON格式与Claude Desktop相同(mcpServers 顶级密钥）。

帆板运动

~/.codeium/windsurf/mcp_config.jsonJSON格式与Claude Desktop相同。

自定义存储路径（macOS）

如果您的本地Simplenote数据不在默认路径上：

1. 打开查找器，按 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存储在 telemetry.json 在与相同的配置目录下 config.json 并以如下方式发送 _ui 和 _ut=simplenote:local_uuid.

跟踪的事件仅限于设置选项(type、操作系统系列、写入模式和API设置的身份验证方法）和工具调用(tool、提供者、成功/失败）。笔记ID、笔记内容、标签、搜索查询、Simplenote帐户详细信息和令牌永远不会发送。

要选择退出一次跑步，请设置：

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

要持续选择退出：

npx @automattic/simplenote-mcp disable-telemetry

当在建筑后从本地结账处运行时， node server.js disable-telemetry 也工作。

提供商解析

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

1. --path --强制本地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 （string，必填）--注释内容（第一行成为标题）
• tags （字符串数组，可选）--要附加的标签
• markdown （boolean，可选，默认值：true）--启用markdown渲染
• pinned （boolean，可选，默认值：false）--固定到列表顶部

退货： {success, id, version, title}

update_note

更新现有注释。编写工具-需要编写模式和Simperium API提供程序。

重要提示： content 和 tags 完全替换现有值。当只更改注释的一部分时，请致电 get_note 首先，将合并后的内容传回。部分值将擦除其余值。

参数：

• id （字符串，必填）--注释ID
• content （字符串，可选）--新注释内容
• tags （字符串数组，可选）--替换标记列表（提供完整列表）
• markdown （布尔值，可选）--启用/禁用markdown渲染
• pinned （布尔值，可选）--pin/unpin

至少其中之一 content, tags, markdown，或 pinned 必须提供。

退货： {success, id, version}

垃圾记

软删除笔记（移动到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 （number，可选，默认值：10，最大值：25）--要返回的最大版本数

退货： {id, current_version, entries: [{version, modified_at, content_preview}]} 排序为当前第一。Simperium保留窗口之外的版本会被自动删除——不连续 version 数字表明了差距。

get_note_version

获取笔记特定历史版本的完整内容。只读操作；需要在当前服务器中启用写入模式的Simperium API提供程序。用于在呼叫前预览内容 revert_note.

参数：

• id （字符串，必填）--注释ID
• version （number，必填）--版本号（正整数）

退货： {id, version, content, tags, pinned, markdown, deleted, created, modified}.投掷 version_not_found 如果版本在Simperium的保留窗口之外。

revert_note

将笔记还原到以前的版本。计入写入速率预算。绕过被丢弃的纸币保护——恢复到未被丢弃的版本将取消丢弃；恢复到已丢弃的版本将重新丢弃。

推荐流量： get_note_history → get_note_version （预览）→ revert_note.

参数：

• id （字符串，必填）--注释ID
• version （number，必填）--要还原的目标版本（正整数）

退货： {success, id, reverted_from_version, new_version, no_op}. no_op: true 意味着目标版本与当前版本相同——没有执行写入操作，也没有消耗费率预算。

需要在中启用写入模式 simplenote-mcp setup保留由Simperium决定，不可从客户端配置。

示例用法

配置后，您可以向AI客户端询问以下问题：

• “列出我的Simplenote标签”
• “显示我最近的笔记”
• “在我的笔记中搜索‘食谱’”
• “显示标记为‘ideas’的笔记”
• “获取note\[id\]的完整内容”
• “显示\[注释标题\]的版本历史记录”
• “让我看看那张纸条的第42版是什么样子的”
• “将该注释还原为以前的版本”

写入工具（创建、更新、废弃、恢复、还原）默认情况下是关闭的，并且仅可用于Simperium API提供商。跑 simplenote-mcp setup 并选择加入以启用它们。本地macOS数据缓存在内存中，并在存储文件更改时刷新；Simperium API响应被缓存60秒，如果API短暂无法访问，则stale-cache会回退。

Windows笔记

一些Windows特有的怪癖值得了解：

• 包裹 npx 在 cmd /c 克劳德桌面。它的子进程启动器并不总是能找到 npx.cmd 在PATH上，否则：

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

• 克劳德桌面版 %APPDATA% 扩张 在某些版本中可能会默默失败。如果服务器找不到其配置目录，请设置 APPDATA 明确在 env 块：

  "env": {
    "APPDATA": "C:\\Users\\\\AppData\\Roaming"
  }

• 带有反斜线的路径 JSON格式必须转义("C:\\Users\\...").正斜杠也有效("C:/Users/...")并且不易出错。

故障排除

“找不到配置。运行 simplenote-mcp setup..." 跑 npx -y @automattic/simplenote-mcp setup 在启动MCP客户端之前。

“未登录。运行 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.如果您没有桌面应用程序，请使用切换到API路径 simplenote-mcp setup.

第一次工具调用非常缓慢 npx -y 首次使用时下载该包。在慢速网络上，这可能会超过MCP客户端的启动超时（~10s）。要么等待它预热，要么全局安装一次： npm install -g @automattic/simplenote-mcp 和改变 "command": "npx" 到 "command": "simplenote-mcp" （删除参数）。

“找不到命令：Windows上的npx”/“spawn npx ENOENT” 看 cmd /c 包装 Windows笔记.

安装程序电子邮件未到达 检查垃圾邮件。身份验证端点是速率受限的——快速连续的多次失败将使IP锁定约10分钟。请稍候，然后重试。

一切看起来都很好，但数据似乎过时了 Simperium响应缓存60秒；当存储文件的mtime更改时，本地macOS提供程序会刷新。请稍等，或重新启动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检查员进行本地测试

MCP检查员 为您提供MCP服务器的浏览器UI——它列出了服务器公开的工具、提示和资源，允许您使用任意参数调用它们，并在两侧打印原始JSON-RPC。当您想在不将服务器连接到真实客户端的情况下进行代码更改时，这很有用。

运行本地版本：

npm run build
npm run inspect

打开它打印的URL并单击 连接.

从源代码运行而不重建 （最快迭代--使用 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' 和a auth.json 令牌。然后，检查器自动选择API提供程序。要为会话使用其他令牌，请导出 SIMPLENOTE_TOKEN 启动检查器之前（覆盖 auth.json)，或将其粘贴到检查器UI中 环境变量 面板。

Inspector将服务器作为stdio上的子进程生成，因此任何在真正的MCP客户端配置中工作的东西都可以在这里工作——包括 --path、env变量和备用节点二进制文件。

使用Claude Code进行本地测试

回购包括一个项目范围 .mcp.json 将本地源注册为名为的服务器 simplenote-dev。当您在repo目录中打开Claude Code时，它会提供启用该服务器的功能（自文件提交以来，您将在第一次收到权限提示）。启用后，此目录中的Claude Code会话将通过以下方式与正在进行的代码进行对话 node --import tsx src/server.ts --不需要构建步骤。

工作流程：

1. 跑 npm install 所以 tsx 可用，以及 simplenote-mcp setup 一次，如果你还没有；开发服务器读取相同的内容 config.json/auth.json 作为正常安装。
2. 在repo目录中打开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包存在之前连接指向本地克隆的配置的用户保持稳定。

许可证

麻省理工学院