Zettelkasten MCP服务器使用说明

项目简介

Zettelkasten MCP服务器是一个实现了 Model Context Protocol (MCP) 的后端应用，它将 Zettelkasten (卡片盒) 知识管理方法与现代 LLM 技术相结合。Zettelkasten 是一种由德国社会学家 Niklas Luhmann 发明的知识管理系统，强调原子化笔记、笔记间的连接以及知识的涌现。本项目旨在通过 MCP 协议，让 LLM 客户端（如 Claude）能够便捷地访问和操作您的 Zettelkasten 知识库，实现 AI 辅助的知识管理。

主要功能点

原子化笔记管理：创建、检索、更新和删除以 Markdown 格式存储的原子笔记。
双向链接：在笔记之间建立双向链接，构建知识网络。
标签分类：使用标签对笔记进行分类和组织。
多维度搜索：支持按内容、标签、链接等多种方式搜索笔记。
知识图谱探索：通过链接关系，支持垂直和水平的知识探索。
与 Claude 集成：通过 MCP 协议与 Claude 等 LLM 客户端无缝集成，实现 AI 辅助的知识管理和知识库交互。
双重存储架构：
- Markdown 文件: 作为数据源，易于编辑、版本控制和备份。
- SQLite 数据库: 作为索引层，提供高效查询和快速链接遍历。
丰富的工具集：提供一系列以 'zk_' 开头的 MCP 工具，用于知识库的各种操作。

安装步骤

克隆仓库:

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 pip install -e .
```

服务器配置

复制并编辑 '.env' 文件:
```
cp .env.example .env
```
根据需要编辑 '.env' 文件，例如配置笔记目录和数据库路径。默认配置通常已足够使用。

Claude Desktop MCP 服务器配置 (JSON 格式):

将以下 JSON 配置添加到您的 Claude Desktop 应用的 MCP 服务器配置中。请务必将 '/absolute/path/to/zettelkasten-mcp' 替换为您的 'zettelkasten-mcp' 仓库的绝对路径。

{
  "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" // 日志级别，可选 DEBUG, INFO, WARNING, ERROR, CRITICAL
      }
    }
  }
}

配置参数说明:

'"zettelkasten"': MCP 服务器的名称，在 Claude Desktop 中用于标识和选择该服务器。
'"command"': 启动服务器的命令，指向虚拟环境中的 Python 解释器。
'"args"': 传递给 Python 解释器的参数，'-m zettelkasten_mcp.main' 表示运行 'zettelkasten_mcp.main' 模块。
'"env"': 环境变量配置，用于指定笔记目录、数据库路径和日志级别。

基本使用方法

启动服务器:

在 'zettelkasten-mcp' 仓库根目录下，运行以下命令启动 MCP 服务器：

python -m zettelkasten_mcp.main

或者使用显式配置启动：

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

连接 Claude Desktop:

确保已将上述 JSON 配置添加到 Claude Desktop 的 MCP 服务器配置中，并在 Claude 中选择名为 "zettelkasten" 的 MCP 服务器。
通过 Claude 与 Zettelkasten 知识库交互:

现在您可以在 Claude 中使用 '@zettelkasten' 前缀加上可用的 MCP 工具命令来操作您的 Zettelkasten 知识库。例如，使用 'zk_create_note' 工具创建新笔记，使用 'zk_search_notes' 工具搜索笔记等。具体的工具列表请参考仓库 README.md 中的 "Available MCP Tools" 部分。

注意: 首次使用或手动修改 Markdown 文件后，可能需要运行 'zk_rebuild_index' 工具重建数据库索引，以确保数据同步。

Zettelkasten MCP服务器