Zettelkasten MCP 服务器

一个实现了Zettelkasten知识管理方法的模型上下文协议（MCP）服务器，允许您通过Claude和其他兼容MCP的客户端创建、链接、探索和综合原子笔记。

什么是Zettelkasten？

Zettelkasten方法是由德国社会学家尼古拉斯·卢曼开发的一种知识管理系统，他利用这种方法创作了超过70本书籍和数百篇文章。它由三个核心原则组成：

1. 原子性：每个笔记只包含一个想法，使其成为知识的一个独立单元。
2. 连接性：笔记相互链接，形成一个知识网络，其中的想法之间具有有意义的关系。
3. 涌现性：随着网络的增长，新的模式和见解会浮现出来，这些在单独创建笔记时并不明显。

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

• 垂直探索：通过在一个主题领域内跟随连接来深入特定话题。
• 水平探索：通过跨领域的链接发现不同领域之间的意外关系。

这种结构鼓励在从一个笔记到另一个笔记的过程中偶然发现，同时通过其独特的标识符保持每条信息易于访问。卢曼称他的系统为他的“第二大脑”或“交流伙伴”——这个数字实现旨在通过现代技术提供类似的好处。

功能

• 创建带有唯一时间戳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这样的工具包含源代码。

存储架构

该系统采用双存储方法：

1. Markdown 文件：所有笔记都存储为人类可读的Markdown文件，并带有用于元数据的YAML前言。这些文件是事实来源，并且可以：

   • 在任何文本编辑器中直接编辑
   • 放入版本控制（Git等）
   • 使用标准文件备份程序进行备份
   • 像其他文本文件一样共享或传输

2. SQLite 数据库：作为索引层，它：

   • 促进高效查询和搜索操作
   • 允许Claude快速遍历知识图谱
   • 维护关系信息以加快链接遍历
   • 当需要时，可以从Markdown文件自动重建

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

安装

# 克隆仓库
git clone https://github.com/entanglr/zettelkasten-mcp.git
cd zettelkasten-mcp

# 创建虚拟环境
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate

# 安装依赖
uv add "mcp[cli]"

# 安装开发依赖
uv sync --all-extras

配置

在项目根目录创建一个.env文件并复制示例：

cp .env.example .env

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

使用

启动服务器

python -m zettelkasten_mcp.main

或者使用显式配置：

python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db

连接到Claude Desktop

在您的Claude Desktop中添加以下配置：

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": [
        "-m",
        "zettelkasten_mcp.main"
      ],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE_PATH": "/absolute/path/to/zettelkasten-mcp/data/db/zettelkasten.db",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

可用的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/
├── src/
│   └── zettelkasten_mcp/
│       ├── models/       # 数据模型
│       ├── storage/      # 存储层
│       ├── services/     # 业务逻辑
│       └── server/       # MCP服务器实现
├── data/
│   ├── notes/            # 笔记存储（Markdown文件）
│   └── db/               # 索引数据库
├── tests/                # 测试套件
├── .env.example          # 环境变量模板
└── README.md

测试

涵盖从数据模型到MCP服务器实现的所有应用层的Zettelkasten MCP测试套件。

如何运行测试

从项目根目录运行：

直接使用pytest

python -m pytest -v tests/

使用UV

uv run pytest -v tests/

带覆盖率报告

uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/

运行特定测试文件

uv run pytest -v tests/test_models.py

运行特定测试类

uv run pytest -v tests/test_models.py::TestNoteModel

运行特定测试函数

uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation

测试目录结构

tests/
├── conftest.py - 所有测试的公共fixture
├── test_integration.py - 整个系统的集成测试
├── test_mcp_server.py - MCP服务器工具的测试
├── test_models.py - 数据模型的测试
├── test_note_repository.py - 笔记存储库的测试
├── test_search_service.py - 搜索服务的测试
├── test_semantic_links.py - 语义链接的测试
└── test_zettel_service.py - Zettel服务的测试

重要通知

⚠️ 自行承担风险：此软件是实验性的，按原样提供，没有任何形式的担保。虽然已经努力确保数据完整性，但可能存在的错误可能导致数据丢失或损坏。始终定期备份您的笔记，并在测试重要信息时谨慎行事。

致谢

这个MCP服务器是在Claude的帮助下制作的，Claude帮助将这个项目的原子思想组织成一个连贯的知识图谱。就像一个好的Zettelkasten系统一样，Claude连接了原本可能孤立的想法。然而，与卢曼的纸质系统不同的是，Claude不需要9万张索引卡就能有效工作。

许可证

MIT许可证