Drafta 笔记桥 rpegorov/drafta-mcp

drafta-mcp

一个 Model Context Protocol 服务器，把 Drafta 笔记库开放给 AI 助手 —— Claude Code、Zed，或任何通过 stdio 启动服务器的 MCP 客户端。

助手可以搜索和读取你的笔记，并且（除非你用 --read-only 启动服务器）创建笔记、追加内容、打标签、设置状态、归档到笔记本。它写入的所有内容都落在 Drafta 应用读取的同一批 Markdown 文件里，所以聊天中创建的笔记和你手打的笔记没有区别。

隐私

这个仓库存在的意义，是让你自己核查笔记去了哪里。答案是：哪儿也没去。

- 只用 stdio。 服务器通过 stdin 和 stdout 与启动它的客户端通信。它不开套接字，也不监听端口。
- 只碰本地文件。 它只读写库目录下的文件，别的什么都不碰。它从不接触应用的设置、钥匙串条目或同步状态。
- 不联网。 这个包里没有任何代码发起网络请求。Sources/ 里没有 URLSession、Network 框架或套接字；唯一的依赖是官方 MCP Swift SDK，只用到它的 stdio 传输。
- 没有账号，没有许可证校验，没有遥测。

你的笔记暴露给谁，取决于 MCP 客户端怎么处理它读到的文本 —— 那部分由你连接的客户端决定。

构建

需要 macOS 13 或更高版本，以及 Swift 6（Xcode 16 或更新版本）。

swift build -c release

二进制文件在 .build/release/drafta-mcp。

swift test # the test suite

安装

把二进制文件复制到一个稳定的位置，例如：

install -m 755 .build/release/drafta-mcp /usr/local/bin/drafta-mcp

用法

usage: drafta-mcp [--library <path>] [--read-only]

-l, --library <path> library root (default: ~/Library/Application Support/Drafta/Library)
-r, --read-only publish read tools only
-h, --help print this help and exit

不带 --library 时，服务器打开 Drafta 应用使用的库。路径里的 ~ 由服务器展开，因为客户端配置是 JSON，没有 shell 会处理它。未知参数会报错：--readonly（拼写错误）不会启动一个可写服务器。

Claude Code

claude mcp add drafta -- /usr/local/bin/drafta-mcp --library "~/Library/Application Support/Drafta/Library"

在末尾加上 --read-only，助手就只拥有读权限。

Claude Code 插件

这个仓库同时也是一个 Claude Code 插件市场。插件会启动 Drafta.app 内置的 drafta-mcp 辅助程序，所以需要 /Applications 里有 Drafta.app。

/plugin marketplace add rpegorov/drafta-mcp
/plugin install drafta@drafta

插件用默认配置运行服务器（应用的库，读写权限）。如果需要只读访问，或者 Drafta.app 装在 ~/Applications，请自己用 claude mcp add 注册辅助程序，并传入 --read-only 或完整路径；参见 plugins/drafta/README.md。

Claude Desktop（MCPB）

从 Releases 页面下载 drafta-mcp.mcpb，双击即可。这个包不含二进制文件：它启动的是 Drafta.app 内置的 drafta-mcp 辅助程序，所以要求 /Applications 下装有 Drafta.app。也可以用 scripts/build-mcpb.sh 从源码构建。

Codex

codex plugin marketplace add rpegorov/drafta-mcp
codex plugin add drafta@drafta

插件启动的是 Drafta.app 内置的辅助程序，所以要求 /Applications 下装有 Drafta.app。

DeepSeek Harness（DSH）

plugins/dsh-drafta 为 Drafta 辅助程序添加一行 @deepseek-ai/dsh-mcp-client（dsh-drafta-mcp）。把包加进你配置档的 package.json，方式和任何本地插件一样，用 link: 依赖，并在 dsh.profile.bundles 下列出：

{
"dependencies": { "dsh-drafta": "link:/path/to/drafta-mcp/plugins/dsh-drafta" },
"dsh": { "profile": { "bundles": ["dsh-drafta"] } }
}

如果你已经手动把 Drafta 加进了 DSH，删掉两者中的一个：它们都会注册名为 drafta 的服务器。

Zed

在 settings.json 中：

{
"context_servers": {
"drafta": {
"command": "/usr/local/bin/drafta-mcp",
"args": ["--library", "~/Library/Application Support/Drafta/Library"]
}
}
}

工具

读取类工具（始终发布）：

| 工具 | 作用 |
| search_notes | 全文搜索标题、正文和标签，可按 tag、status、notebook 过滤；最新的排前面，limit 最大 100。查询为空时列出最近的笔记。 |
| read_note | 按 id 或精确标题读取一条笔记的完整内容。 |
| list_notebooks | 列出笔记本及其层级。 |
| list_tags | 列出所有在用的标签。 |
| formatting_guide | Drafta 渲染的 Markdown：callouts、mermaid、任务列表、标签、wiki 链接、数学公式。 |

写入类工具（带 --read-only 时不发布）：

| 工具 | 作用 |
| create_note | 新建笔记；不给笔记本就放进 Inbox。可选 tags 和 status。 |
| append_to_note | 在末尾追加文本；原文本保留为一个修订版本。 |
| update_note | 替换正文；原文本保留为一个修订版本。 |
| set_note_status | active、onHold、completed、dropped 或 none。 |
| tag_note | 添加标签（数组，或逗号分隔的字符串）。 |
| create_notebook | 创建笔记本，或返回同名的已有笔记本。 |
| trash_note | 把笔记移到废纸篓；文件保留。 |

笔记也会作为 MCP 资源发布（drafta://note/<uuid>，最近 200 条），客户端不用调用工具就能把一条笔记作为上下文附上。

库格式

库就是一个普通目录：

Library/
library.json notebooks (pretty-printed, sorted JSON)
notes/<UUID>.md one note: YAML front matter + Markdown body
revisions/<UUID>/<ms>.md previous bodies of a note, one file per revision
editor-hold.json 应用持有未保存文本时由应用写入

如果你要自己读写这些文件，有几点值得了解：

- 标签不存储。 每次读取时都从正文里的 #tags 推导出来；只有单独添加的标签才存放在 front-matter 的 extraTags 字段里。
- 标题就是正文的第一行。 正文没有标题时，create_note 会写一个 # heading 作为标题。
- 没有笔记本的笔记是孤儿，只在 All Notes 下可见，所以新笔记会归入 Inbox（不存在就创建）。
- 编辑保留历史。 update_note 和 append_to_note 把被替换的文本存到 revisions/ 下（每条笔记 30 份），应用在这里把它显示为历史。
- 打开的笔记受保护。 Drafta 应用持有某条笔记的未保存文本时，会把这条笔记列进 editor-hold.json；update_note 和 append_to_note 拒绝写入该笔记的正文并给出提示，而不是报告一次成功、随后又被应用覆盖掉。
- library.json 在文件协调下编辑，所以应用同一时刻新增的笔记本不会丢失。

无论应用是否在运行，服务器都能工作。应用在运行时，它的文件监视器会拾取服务器写入的内容。

与 Drafta.app 的关系

Drafta.app 在应用包内自带一份 drafta-mcp。本仓库不是那个二进制文件。 它是同一个服务器的独立快照，社区可以编辑：工具名相同、参数相同、磁盘格式相同，只是去掉了应用的许可证校验——这里的写入只受 --read-only 约束。两者分开开发，可能产生差异；如果应用将来改了库格式，这份快照不会自动跟进。

欢迎贡献。

许可证

Apache License 2.0 —— 见 LICENSE 和 NOTICE。

Кратко по-русски

drafta-mcp — MCP-сервер для библиотеки заметок Drafta. Работает только через stdio, читает и пишет только файлы в каталоге библиотеки и не делает ни одного сетевого запроса. Сборка: swift build -c release. Подключение к Claude Code: claude mcp add drafta -- /путь/к/drafta-mcp --library <путь к библиотеке>. Флаг --read-only оставляет только инструменты чтения. Это независимый снимок сервера, а не бинарник, который поставляется внутри Drafta.app.

M8ven Score