shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

zettelkasten-mcp

一个基于Zettelkasten知识管理方法的MCP服务器，允许用户通过Claude等MCP兼容客户端创建、链接、探索和合成原子化笔记，实现个人知识图谱的构建与管理。

article

README

🚀 卡片盒笔记法MCP服务器

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

smithery徽章

🚀 快速开始

安装

通过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 目录包含了开始所需的文件：

系统提示

选择以下其中一个：

项目知识（面向最终用户）

聊天提示

项目知识（面向开发者和贡献者）

注意：可以选择使用 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中打开项目以激活工作区设置；你可能需要安装扩展并重新加载窗口。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client