AI导哈

知识管理服务器

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

  • by entanglr
  • Python
  • 本地部署
  • 167 星标
  • 更新于
在 GitHub 查看 entanglr/zettelkasten-mcp

使用说明

MCP 服务器

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

Zettelkasten是什么？

Zettelkasten方法是德国社会学家Niklas Luhmann开发的一种知识管理系统，他用它制作了70多本书和数百篇文章。它由三个核心原则组成：

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

Zettelkasten方法之所以强大，是因为它能够以多种方式进行探索：

  • 垂直勘探：通过以下主题领域内的联系，深入探讨特定主题。
  • 水平勘探：通过遍历跨域的链接来发现不同字段之间的意外关系。

这种结构在你从一个音符到另一个音符追踪思想轨迹时，会带来偶然的发现，同时通过其唯一标识符使每条信息易于访问。卢曼称他的系统为“第二大脑”或“沟通伙伴”，这种数字实现旨在通过现代技术提供类似的好处。

特性

  • 使用基于时间戳的唯一ID创建原子笔记
  • 双向链接笔记以构建知识图
  • 分类组织的标记注释
  • 按内容、标签或链接搜索笔记
  • 使用markdown格式进行人类可读性和编辑
  • 通过MCP与Claude集成，实现人工智能辅助知识管理
  • 双存储架构（见下文）
  • 简化架构的同步操作模型

例子

注释类型

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 此存储库中的目录包含入门所需的文件：

系统提示

选择一个：

项目知识

对于终端用户：

聊天提示

项目知识（dev）

对于开发者和贡献者：

注意：可选择使用以下工具包含源代码 再混合.

存储体系结构

此系统使用双存储方法：

  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桌面：

{
  "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系统一样，克劳德将原本可能保持孤立的想法联系起来。然而，与卢曼的纸质系统不同，克劳德不需要9万张索引卡就能生效。

许可证

MIT许可证

相关 MCP