Zettelkasten MCP

🚀 卡片盒笔记法MCP服务器

这是一个实现了卡片盒笔记法（Zettelkasten）知识管理方法的模型上下文协议（MCP）服务器。借助该服务器，你可以通过Claude和其他兼容MCP的客户端来创建、关联、探索和整合原子笔记。

🚀 快速开始

安装

通过Smithery安装

要通过 Smithery 自动为Claude桌面版安装卡片盒笔记法MCP服务器，可运行以下命令：

npx -y @smithery/cli install zettelkasten-mcp --client claude

通过uvx安装

uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

本地开发安装

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

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

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

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

配置

在项目根目录下，通过复制示例文件来创建一个 .env 文件：

cp .env.example .env

然后编辑该文件，配置你的连接参数。

若要使用PostgreSQL而非自带的SQLite数据库，需安装可选驱动，并将 ZETTELKASTEN_DATABASE 指向一个SQLAlchemy的URL：

pip install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

使用pipx：

pipx install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

ZETTELKASTEN_DATABASE 可以接受一个文件系统路径（默认是 ./data/db/zettelkasten.db）或任何SQLAlchemy兼容的URL。为了向后兼容，旧的 ZETTELKASTEN_DATABASE_PATH / ZETTELKASTEN_DATABASE_URL 变量仍然有效。

若要支持MySQL或MariaDB，需安装 mysql 扩展，并使用 pymysql 驱动提供一个URL：

pip install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

使用pipx：

pipx install "zettelkasten-mcp[mysql]"
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

对于Microsoft SQL Server，需安装 sqlserver 扩展，并指向一个ODBC连接字符串（需要相应的系统ODBC驱动，例如 ODBC Driver 18 for SQL Server）：

pip install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

使用pipx：

pipx install "zettelkasten-mcp[sqlserver]"
export ZETTELKASTEN_DATABASE="mssql+pyodbc://user:password@server/database?driver=ODBC+Driver+18+for+SQL+Server"

启动服务器

python -m zettelkasten_mcp

或者使用显式配置：

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

或者使用PostgreSQL：

python -m zettelkasten_mcp --notes-dir ./data/notes \
  --database postgresql+psycopg://user:password@localhost:3306/zettelkasten

连接到Claude桌面版

使用smithery

npx -y @smithery/cli install zettelkasten-mcp --client claude

手动配置

在你的Claude桌面版中添加以下配置：

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": ["-m", "zettelkasten_mcp"],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE": "postgresql+psycopg://user:password@localhost:3306/zettelkasten",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

将 ZETTELKASTEN_DATABASE 设置为SQLite的文件系统路径或任何SQLAlchemy URL（例如PostgreSQL），以选择后端。

✨ 主要特性

• 使用基于时间戳的唯一ID创建原子笔记。
• 双向关联笔记，构建知识图谱。
• 为笔记添加标签，进行分类组织。
• 按内容、标签或关联搜索笔记。
• 使用Markdown格式，便于人类阅读和编辑。
• 通过MCP与Claude集成，实现AI辅助知识管理。
• 采用双存储架构（详见下文）。
• 同步操作模型，简化架构。

📦 安装指南

通过Smithery安装

npx -y @smithery/cli install zettelkasten-mcp --client claude

通过uvx安装

uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

本地开发安装

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

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

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

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

💻 使用示例

知识创建示例

A small Zettelkasten knowledge network about the Zettelkasten method itself

📚 详细文档

什么是卡片盒笔记法？

卡片盒笔记法是由德国社会学家尼克拉斯·卢曼（Niklas Luhmann）开发的一种知识管理系统，他利用该系统撰写了70多本书和数百篇文章。该方法包含三个核心原则：

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

卡片盒笔记法的强大之处在于它支持多种探索方式：

• 纵向探索：通过跟随某个主题领域内的关联，深入研究特定主题。
• 横向探索：通过跨越不同领域的关联，发现不同领域之间意想不到的关系。

这种结构允许你在笔记之间跟随思路进行探索，从而实现意外的发现，同时通过每个笔记的唯一标识符，使每条信息都易于访问。卢曼称他的系统为“第二大脑”或“交流伙伴”——这个数字实现旨在通过现代技术提供类似的益处。

笔记类型

卡片盒笔记法MCP服务器支持不同类型的笔记：

类型	处理方式	描述
临时笔记	fleeting	用于快速记录想法的临时笔记
文献笔记	literature	阅读材料时记录的笔记
永久笔记	permanent	经过精心构思、长期有效的笔记
结构笔记	structure	用于组织其他笔记的索引或大纲笔记
中心笔记	hub	关于关键主题的卡片盒笔记法的入口点

关联类型

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

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

提示

为了确保最大的有效性，建议在要求大语言模型（LLM）处理信息、探索或整合你的卡片盒笔记时，使用系统提示（“项目说明”）、项目知识和适当的聊天提示。本仓库的 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. 数据库索引：作为一个索引层，它：

   • 便于高效的查询和搜索操作。
   • 使Claude能够快速遍历知识图谱。
   • 维护关系信息，以便更快地进行关联遍历。
   • 在需要时自动从Markdown文件中重建。
   • 默认使用SQLite；通过 ZETTELKASTEN_DATABASE 提供一个SQLAlchemy URL，可使用PostgreSQL或其他后端。

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

可用的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服务器有一个全面的测试套件，覆盖了从模型到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 - 卡片盒服务的测试

重要提示

⚠️ 重要提示

本软件为实验性软件，按“原样”提供，不提供任何形式的保证。尽管已尽力确保数据完整性，但它可能包含潜在导致数据丢失或损坏的错误。请定期备份你的笔记，并在使用重要信息进行测试时谨慎操作。

致谢

这个MCP服务器是在Claude的帮助下创建的，Claude帮助将该项目的原子化想法组织成一个连贯的知识图谱。就像一个优秀的卡片盒笔记法系统一样，Claude连接了那些原本可能孤立的想法。不过，与卢曼的纸质系统不同，Claude不需要90,000张索引卡就能发挥作用。

许可证

本项目采用MIT许可证。

预提交（代码格式化）

为了保持代码风格一致，本项目使用 pre-commit 并配置了 black 和 isort。 在本地安装并启用钩子：

pip install pre-commit
pre-commit install
pre-commit run --all-files

如果你使用虚拟环境，请确保在运行 pre-commit install 之前激活该环境，以便钩子指向正确的Python解释器。

编辑器配置（VS Code）

本项目包含了Visual Studio Code的推荐设置，以实现自动导入补全和保存时自动组织导入。工作区设置位于 .vscode/settings.json，推荐的扩展位于 .vscode/extensions.json。

推荐的VS Code扩展：

• ms-python.python — Python语言支持
• ms-python.vscode-pylance — Pylance语言服务器（提供自动导入补全）

重要设置（已配置）：

• python.analysis.autoImportCompletions: true — 在补全中显示自动导入建议
• editor.codeActionsOnSave.source.organizeImports: true — 保存时运行导入排序
• editor.formatOnSave: true，使用Black作为格式化器

在VS Code中打开项目以激活工作区设置；你可能需要安装扩展并重新加载窗口。