drafta-mcp

A Model Context Protocol server that exposes a
Drafta note library to an AI assistant — Claude Code, Zed, or
any other MCP client that launches servers over stdio.

The assistant can search and read your notes, and (unless you start the server
with --read-only) create notes, append to them, tag them, set their status and
file them into notebooks. Everything it writes lands in the same Markdown files the
Drafta app reads, so a note created from a chat is indistinguishable from one you
typed.

Privacy

This repository exists so that you can check for yourself where your notes go.
The answer is: nowhere.

• stdio only. The server talks to the client that launched it over stdin and
  stdout. It opens no socket and listens on no port.
• Local files only. It reads and writes files under the library directory and
  nothing else. It never touches the app's settings, keychain items or sync state.
• No network. No code in this package makes a network request. There is no
  URLSession, Network framework or socket anywhere in Sources/; the only
  dependency is the official MCP Swift SDK, used for its stdio transport.
• No accounts, no licence check, no telemetry.

What your notes are exposed to is whatever the MCP client does with the text it
reads — that part is up to the client you connect.

Build

Requires macOS 13 or later and Swift 6 (Xcode 16 or newer).

swift build -c release

The binary is .build/release/drafta-mcp.

swift test   # the test suite

Install

Copy the binary somewhere stable, for example:

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

Usage

usage: drafta-mcp [--library ] [--read-only]

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

Without --library the server opens the library the Drafta app uses. A ~ in the
path is expanded by the server, since client configs are JSON and no shell sees
them. An unknown flag is an error: --readonly (a typo) does not start a
writable server.

Claude Code

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

Add --read-only at the end to give the assistant read access only.

Claude Code plugin

This repository is also a Claude Code plugin marketplace. The plugin starts the
drafta-mcp helper that ships inside Drafta.app, so it requires Drafta.app in
/Applications.

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

The plugin runs the server with its defaults (the app's library, read and write).
For read-only access, or for Drafta.app in ~/Applications, register the helper
yourself with claude mcp add and pass --read-only or the full path; see
plugins/drafta/README.md.

Claude Desktop (MCPB)

Download drafta-mcp.mcpb from the Releases
page and double-click it. The bundle contains no binary: it starts the drafta-mcp
helper that ships inside Drafta.app, so it requires Drafta.app in /Applications.
Build it from source with scripts/build-mcpb.sh.

Codex

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

The plugin starts the helper inside Drafta.app, so it needs Drafta.app in /Applications.

DeepSeek Harness (DSH)

plugins/dsh-drafta adds a @deepseek-ai/dsh-mcp-client row (dsh-drafta-mcp) for the
Drafta helper. Add the package to your profile's package.json the same way as any
local plugin, with a link: dependency, and list it under dsh.profile.bundles:

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

If you already added Drafta to DSH by hand, remove one of the two: both register a
server named drafta.

Zed

In settings.json:

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

Tools

Read tools (always published):

Write tools (not published with --read-only):

Notes are also published as MCP resources (drafta://note/, the 200 most
recent), so a client can attach one as context without a tool call.

Library format

A library is a plain directory:

Library/
library.json              notebooks (pretty-printed, sorted JSON)
notes/.md           one note: YAML front matter + Markdown body
revisions//.md  previous bodies of a note, one file per revision
editor-hold.json          written by the app while it holds unsaved text

Things worth knowing if you read or write these files yourself:

• Tags are not stored. They are derived from #tags in the body on every read;
  only tags added separately live in the extraTags front-matter field.
• The title is the first line of the body. create_note writes the title as
  a # heading when the body has none.
• A note without a notebook is an orphan, visible only under All Notes, so new
  notes are filed into the Inbox (created if missing).
• Edits keep history. update_note and append_to_note save the replaced
  text under revisions/ (30 per note), where the app shows it as history.
• Open notes are protected. While the Drafta app holds unsaved text for a note,
  it lists that note in editor-hold.json; update_note and append_to_note
  refuse to write that note's body and say so, instead of reporting a success the
  app would overwrite a moment later.
• library.json is edited under file coordination, so a notebook the app adds
  at the same moment is not lost.

The server works whether or not the app is running. When it is, the app's file
watcher picks up what the server wrote.

Relationship to Drafta.app

Drafta.app ships its own copy of drafta-mcp inside the app bundle. This
repository is not that binary. It is an independent, community-editable snapshot
of the same server: same tool names, same arguments, same on-disk format, with the
app's licence check removed — writes here are gated only by --read-only. The two
are developed separately and may drift; if the app ever changes its library format,
this snapshot does not follow automatically.

Contributions are welcome.

Licence

Apache License 2.0 — see LICENSE and NOTICE.

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

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