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中打開項目以激活工作區設置；你可能需要安裝擴展並重新加載窗口。