zettelkasten-mcp | 通往MCP之路

Zettelkasten MCP 服务器

一个实现了 Zettelkasten 知识管理方法的 Model Context Protocol (MCP) 服务器，允许您通过 Claude 和其他兼容 MCP 的客户端创建、链接、探索和合成原子笔记。

什么是 Zettelkasten？

Zettelkasten 方法是由德国社会学家 Niklas Luhmann 开发的一种知识管理系统，他使用这种方法撰写了超过 70 本书和数百篇文章。该方法包含三个核心原则：

原子性：每个笔记只包含一个想法，使其成为一个独立的知识单元。

连接性：笔记通过链接相互连接，形成一个知识网络，想法之间建立有意义的关系。

涌现性：随着网络的发展，新的模式和见解会涌现出来，这些在创建单个笔记时并不明显。

Zettelkasten 方法的强大之处在于它支持多种探索方式：

垂直探索：通过跟随主题领域内的连接，深入挖掘特定主题。

水平探索：通过跨越不同领域的链接，发现不同领域之间的意外关系。

这种结构使您在从笔记到笔记的思维轨迹中能够偶然发现新的见解，同时通过唯一的标识符轻松访问每条信息。Luhmann 称他的系统为他的“第二大脑”或“沟通伙伴”——这个数字化的实现旨在通过现代技术提供类似的好处。

功能

创建具有唯一时间戳 ID 的原子笔记

双向链接笔记以构建知识图谱

为笔记添加标签以便分类组织

通过内容、标签或链接搜索笔记

使用 Markdown 格式，便于人类阅读和编辑

通过 MCP 与 Claude 集成，实现 AI 辅助的知识管理

双存储架构（见下文）

同步操作模型，简化架构

示例

知识创建：关于 Zettelkasten 方法本身的一个小型 Zettelkasten 知识网络

笔记类型

Zettelkasten MCP 服务器支持不同类型的笔记：

类型	标识符	描述
临时笔记	`fleeting`	用于快速捕捉想法的临时笔记
文献笔记	`literature`	来自阅读材料的笔记
永久笔记	`permanent`	经过精心撰写的、长期有效的笔记
结构笔记	`structure`	组织其他笔记的索引或大纲笔记
枢纽笔记	`hub`	关键主题的 Zettelkasten 入口点

链接类型

Zettelkasten MCP 服务器使用一个全面的语义链接系统，在笔记之间创建有意义的连接。每种链接类型代表一种特定的关系，从而构建一个丰富的、多维度的知识图谱。

主要链接类型	反向链接类型	关系描述
`reference`	`reference`	简单引用相关信息（对称关系）
`extends`	`extended_by`	一个笔记基于或发展了另一个笔记的概念
`refines`	`refined_by`	一个笔记澄清或改进了另一个笔记
`contradicts`	`contradicted_by`	一个笔记对另一个笔记提出相反的观点
`questions`	`questioned_by`	一个笔记对另一个笔记提出问题
`supports`	`supported_by`	一个笔记为另一个笔记提供证据
`related`	`related`	通用关系（对称关系）

提示

为了确保最大效果，我们建议在使用 LLM 处理信息、探索或合成您的 Zettelkasten 笔记时，使用系统提示（“项目指令”）、项目知识和适当的聊天提示。本仓库的 docs 目录包含以下文件，帮助您快速上手：

系统提示

选择一个：

system-prompt.md

system-prompt-with-protocol.md

项目知识

对于最终用户：

zettelkasten-methodology-technical.md

link-types-in-zettelkasten-mcp-server.md

（更多与您的项目相关的信息）

聊天提示

chat-prompt-knowledge-creation.md

chat-prompt-knowledge-creation-batch.md

chat-prompt-knowledge-exploration.md

chat-prompt-knowledge-synthesis.md

项目知识（开发者）

对于开发者和贡献者：

Example - A simple MCP server.md

MCP Python SDK-README.md

llms-full.txt

注意：可以选择使用 repomix 等工具包含源代码。

存储架构

本系统采用双存储方法：

Markdown 文件：所有笔记都存储为人类可读的 Markdown 文件，并使用 YAML frontmatter 存储元数据。这些文件是事实来源，可以：

在任何文本编辑器中直接编辑

置于版本控制（Git 等）之下

使用标准文件备份程序进行备份

像其他文本文件一样共享或传输

SQLite 数据库：作为索引层，具有以下功能：

促进高效的查询和搜索操作

使 Claude 能够快速遍历知识图谱

维护关系信息以加快链接遍历

在需要时从 Markdown 文件自动重建

如果您在系统外部直接编辑 Markdown 文件，则需要运行 zk_rebuild_index 工具来更新数据库。数据库本身可以随时删除——它将从您的 Markdown 文件重新生成。

安装

配置

通过复制示例文件在项目根目录创建 .env 文件：

然后编辑文件以配置您的连接参数。

使用

启动服务器

或使用显式配置：

连接到 Claude Desktop

将以下配置添加到您的 Claude Desktop：

可用的 MCP 工具

所有工具都以 zk_ 前缀命名，以便更好地组织：

工具	描述
`zk_create_note`	创建带有标题、内容和可选标签的新笔记
`zk_get_note`	通过 ID 或标题检索特定笔记
`zk_update_note`	更新现有笔记的内容或元数据
`zk_delete_note`	删除笔记
`zk_create_link`	在笔记之间创建链接
`zk_remove_link`	删除笔记之间的链接
`zk_search_notes`	通过内容、标签或链接搜索笔记
`zk_get_linked_notes`	查找与特定笔记链接的笔记
`zk_get_all_tags`	列出系统中的所有标签
`zk_find_similar_notes`	查找与给定笔记相似的笔记
`zk_find_central_notes`	查找连接最多的笔记
`zk_find_orphaned_notes`	查找没有连接的笔记
`zk_list_notes_by_date`	按创建/更新日期列出笔记
`zk_rebuild_index`	从 Markdown 文件重建数据库索引

项目结构

测试

Zettelkasten MCP 的全面测试套件，覆盖从模型到 MCP 服务器实现的所有应用层。

如何运行测试

在项目根目录下运行：

使用 pytest 直接运行

使用 UV 运行

生成覆盖率报告

运行特定测试文件

运行特定测试类

运行特定测试函数

测试目录结构

重要通知

⚠️ 使用风险自负：本软件是实验性的，按原样提供，不提供任何形式的担保。虽然已尽力确保数据完整性，但它可能包含导致数据丢失或损坏的错误。请定期备份您的笔记，并在测试重要信息时谨慎使用。

致谢

这个 MCP 服务器是在 Claude 的协助下构建的，它帮助将本项目的原子思想组织成一个连贯的知识图谱。就像一个优秀的 Zettelkasten 系统一样，Claude 连接了那些可能仍然孤立的想法的点。然而，与 Luhmann 的纸质系统不同，Claude 不需要 90,000 张索引卡片就能高效工作。

许可证

MIT 许可证