Zettelkasten MCP Server

Zettelkasten MCP 服务

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

什么是 Zettelkasten？

Zettelkasten 方法是由德国社会学家 Niklas Luhmann 开发的一套知识管理系统。他借助该系统创作了 70 多本书和数百篇文章。它包含三个核心原则：

1. 原子性：每篇笔记只包含一个想法，使其成为一个独立的知识单元
2. 连接性：将笔记相互链接，建立知识网络，并为想法之间构建有意义的联系
3. 涌现性：随着网络不断扩展，新的模式和见解会逐渐涌现，而这些在创建单篇笔记时并不明显

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	通用关系（对称关系）

提示词

为了确保效果最佳，当你让大模型处理信息，或探索、综合 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 frontmatter 保存元数据。这些文件是唯一事实来源，可以：

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

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

   • 高效执行查询和搜索操作
   • 让 Claude 快速遍历知识图谱
   • 维护关系信息，以便更快地遍历链接
   • 在需要时根据 Markdown 文件自动重建

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

安装

# Clone the repository
git clone https://github.com/entanglr/zettelkasten-mcp.git
cd zettelkasten-mcp

# Create a virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv add "mcp[cli]"

# Install dev dependencies
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/       # Data models
│       ├── storage/      # Storage layer
│       ├── services/     # Business logic
│       └── server/       # MCP server implementation
├── data/
│   ├── notes/            # Note storage (Markdown files)
│   └── db/               # Database for indexing
├── tests/                # Test suite
├── .env.example          # Environment variable template
└── README.md

测试

Zettelkasten MCP 的全面测试套件，涵盖应用程序的所有层，从模型到 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 - Common fixtures for all tests
├── test_integration.py - Integration tests for the entire system
├── test_mcp_server.py - Tests for MCP server tools
├── test_models.py - Tests for data models
├── test_note_repository.py - Tests for note repository
├── test_search_service.py - Tests for search service
├── test_semantic_links.py - Tests for semantic linking
└── test_zettel_service.py - Tests for zettel service

重要声明

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

致谢

此 MCP 服务是在 Claude 的协助下打造的。Claude 帮助将本项目中的原子化思想整理成连贯的知识图谱。就像一套优秀的 Zettelkasten 系统一样，Claude 将原本可能彼此孤立的想法串联起来。不过，与 Luhmann 的纸质系统不同，Claude 不需要 90,000 张索引卡也能发挥作用。

许可证

MIT 许可证