mcp-zettel

为 Claude（或任何 MCP 客户端）提供 Zettelkasten 形式的持久化记忆。

这是一个 MCP 服务器，它将个人原子化、互联的 Markdown 知识库暴露给 Claude Desktop、Claude Code、Cursor 或任何兼容 MCP 的客户端。接入后，助手可以创建笔记、使用 [[wiki-links]] 进行交叉引用、按关键词或标签搜索，并遍历反向链接——让你在无需手动复制粘贴的情况下，在不同会话间构建并使用持久化的上下文。

为什么

你与 LLM 开始的每一次对话，对于你已经决定、写下或学到的内容都是零上下文的。Zettelkasten 方法（小型的原子化笔记 + 它们之间明确的链接）非常适合 LLM 可访问的记忆：块自然很小，链接使相关性明确，且存储方式就是你磁盘上的纯 Markdown 文件。

该 MCP 服务器通过 MCP 工具将知识库暴露给任何 LLM 客户端，因此模型可以：

• 创建：当你分享值得保留的决定或见解时，创建一个新笔记

• 搜索：在回答前搜索某个主题的笔记（“关于 X 我做了什么决定？”）

• 链接：双向链接笔记以构建图谱（“这与 [[a3f2c9]] 相矛盾”）

• 遍历反向链接：查找与某个概念相关的所有内容

你将纯 Markdown 文件保存在磁盘上，模型则获得对它们的结构化访问权限。

Related MCP server: obsidian-pkm

在客户端中的样子

连接服务器后，LLM 可以执行如下操作（你的客户端将显示实际的工具调用）：

> What did I conclude about RAG chunk sizes?
[searches notes with query "rag chunk size"]
[reads 2 matching notes]
Based on your notes a3f2c9 ("RAG chunk sizing") and b7e412 ("Sentence-boundary
splitting"), you concluded: 800 chars with ~15% overlap, sentence-aligned.
You flagged that pure character chunking ([[2f00a1]]) hurt recall on your
arxiv set and moved away from it.

暴露的 MCP 工具

此外还有 MCP 资源：

• zettel://all — 所有笔记的单行索引

• zettel://{note_id} — 完整渲染的笔记

• zettel://graph — v0.4. 库中所有笔记 + [[wiki-link]] 的 Mermaid 图表，可由任何支持 markdown+mermaid 的客户端（Claude Desktop、Obsidian、mdBook 等）内联渲染。

• zettel://graph/tag/{tag} — v0.4. 同样的图表，但仅限于带有 {tag} 的笔记及其直接邻居——当完整图表变得过于杂乱时非常有用。

两种搜索工具，而非一种

当你明确知道术语时，关键词搜索是你想要的。它成本低，排名可预测，且精确匹配总是优于听起来相似的匹配。当查询措辞与笔记措辞不匹配时，语义搜索胜出——例如询问“rate limiting”而笔记中称为“throttling”，或者询问“why my cache is cold”而笔记是关于“TTL tuning”的。LLM 可以调用任何有意义的工具；工具描述会告诉它该用哪一个。

默认嵌入模型为 BAAI/bge-small-en-v1.5（384 维，约 130 MB，仅 CPU）。可通过 MCP_ZETTEL_EMBEDDING_MODEL 覆盖。索引在写入后的第一次语义查询时会懒加载重建，因此第一次会有短暂等待——之后它会在服务器进程的生命周期内保留在内存中。

安装

git clone https://github.com/dhruvpatel1706/mcp-zettel.git
cd mcp-zettel
pip install -e .

Python 3.10+。

连接配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或你操作系统上的等效文件，并添加：

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server"
    }
  }
}

重启 Claude Desktop。zettel 工具现在可供模型使用。

Claude Code

claude mcp add zettel -- mcp-zettel-server

Cursor / Continue / 任何 stdio MCP 客户端

将客户端指向 mcp-zettel-server 作为命令；服务器通过 stdio 使用 MCP 协议通信。

自定义存储位置

设置 MCP_ZETTEL_ROOT 以覆盖默认的 ~/.mcp-zettel：

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server",
      "env": { "MCP_ZETTEL_ROOT": "/Users/you/vault" }
    }
  }
}

直接使用 CLI（无需 MCP 客户端）

相同的存储库可以通过纯 CLI 访问——对于希望在 LLM 会话之外检查、编辑或初始化知识库的高级用户非常有用。

mcp-zettel create "RAG chunk sizing" \
  --body "Settled on 800 chars, 15% overlap, sentence-aligned. See [[b7e412]]." \
  --tag rag --tag decisions

mcp-zettel list --tag rag
mcp-zettel search "sentence boundary"
mcp-zettel show a3f2c9
mcp-zettel backlinks a3f2c9

磁盘布局

~/.mcp-zettel/
└── notes/
    ├── a3f2c9.md          ← one markdown file per note
    ├── b7e412.md          ← YAML frontmatter: title, tags, created_at, updated_at
    └── ...                ← body is plain markdown; [[id]] is a wiki-link

每条笔记都是一个独立文件。这意味着：易于备份（git）、易于 grep、无厂商锁定。如果你停止使用此服务器，你仍然拥有一个 Markdown 文件目录。

设计选择

• 文件，而非数据库。 每个 Markdown 文件一条笔记意味着你可以在任何编辑器中编辑、用 git 备份，且无需工具即可检查。存储层只是顶层的一层薄胶水。

• 短十六进制 ID，而非 slug 标题。 [[a3f2c9]] 是稳定的——重命名标题后，所有入站链接仍然有效。也比基于文件名的 slug 更短。

• 双向链接是派生的，而非存储的。 反向链接是通过扫描每条笔记的正文查找 [[target_id]] 在读取时计算出来的。没有需要保持一致的独立索引。在设计规模（≤ 数千条笔记）下非常简单。

• 标题/标签加权搜索。 标题命中计 3 倍权重，标签 2 倍，正文 1 倍。符合直觉：如果笔记标题提到“retrieval”，它比在正文中提到一次该词的笔记更侧重于检索。

• FastMCP，而非底层 MCP。 MCP Python SDK 基于装饰器的 FastMCP 接口意味着工具只是带有 Pydantic 类型参数的 Python 函数——无需手动编写 JSON Schema。

开发

pip install -e ".[dev]"
pytest
black --check src tests
isort --check-only --profile black src tests
flake8 src tests --max-line-length=100 --ignore=E501,W503,E203

CI 在 Python 3.10 / 3.11 / 3.12 上运行。

使用 MCP 检查器交互式检查服务器：

npx @modelcontextprotocol/inspector mcp-zettel-server

提示词模板 (v0.3)

支持提示词菜单的 MCP 客户端（Claude Desktop、Cursor）获得四个服务器端模板，它们编码了执行常见 Zettelkasten 操作的“正确方式”，无需你重新输入指令：

这些只是通过 @mcp.prompt() 注册的返回字符串的函数。将措辞保留在服务器端意味着无论你是从 Claude Desktop、Claude Code 还是 Cursor 调用它，相同的“提炼”提示词表现都是一致的。

路线图

• [x] v0.2 — 嵌入支持的语义搜索与关键词搜索并存

• [x] v0.3 — 用于常见笔记操作的 @mcp.prompt() 模板

• [x] v0.4 — 返回链接 Mermaid 图表的图谱视图资源 (zettel://graph)

• [ ] v0.5 — 用于多设备访问的远程可流式 HTTP 传输

许可证

MIT。参见 LICENSE。