Zettelkasten MCP

🚀 Zettelkasten MCP Server

このZettelkasten MCP Serverは、Model Context Protocol (MCP)を実装したサーバで、Zettelkasten知識管理手法を用いて、Claudeやその他のMCP互換クライアントを通じて、原子的なノートの作成、リンク、探索、合成を可能にします。

🚀 クイックスタート

このサーバを利用することで、効率的な知識管理を行うことができます。以下に、インストール方法や使用例を紹介します。

✨ 主な機能

• 一意のタイムスタンプベースのIDで原子的なノートを作成します。
• ノートを双方向にリンクして、知識グラフを構築します。
• ノートにタグを付けて、カテゴリ別に整理します。
• 内容、タグ、またはリンクでノートを検索します。
• 人間が読みやすく編集しやすいMarkdown形式を使用します。
• MCPを通じてClaudeと統合し、AI支援による知識管理を行います。
• 二重ストレージアーキテクチャを採用しています。
• 同期的な操作モデルを使用し、アーキテクチャを簡素化しています。

📦 インストール

Smitheryを通じたインストール

Smitheryを通じて、Claude Desktop用のZettelkasten MCP Serverを自動的にインストールするには、次のコマンドを実行します。

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

💻 使用例

基本的な使用法

サーバーの起動

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:5432/zettelkasten

Claude Desktopへの接続

smitheryを使用する場合

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

手動で設定する場合

Claude Desktopに以下の設定を追加します。

{
  "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:5432/zettelkasten",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

ZETTELKASTEN_DATABASEをSQLiteのファイルシステムパスまたは任意のSQLAlchemy URL（例: PostgreSQL）に設定して、バックエンドを選択します。

📚 ドキュメント

ノートの種類

Zettelkasten MCPサーバは、さまざまな種類のノートをサポートしています。

リンクの種類

Zettelkasten MCPサーバは、ノート間に意味のある関係を作成する包括的な意味論的リンクシステムを使用しています。

プロンプトの使用

LLMに情報を処理させたり、Zettelkastenノートを探索または合成させる場合、システムプロンプト（「プロジェクトの指示」）、プロジェクトの知識、および適切なチャットプロンプトを使用することをお勧めします。このリポジトリの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ファイル: すべてのノートは、YAMLフロントマターを使用した人間が読みやすいMarkdownファイルとして保存されます。これらのファイルは真の情報源であり、以下のことができます。
   • 任意のテキストエディタで直接編集できます。
   • バージョン管理システム（Gitなど）の下に置くことができます。
   • 標準的なファイルバックアップ手順を使用してバックアップできます。
   • 他のテキストファイルと同じように共有または転送できます。
2. データベースインデックス: インデックス層として機能し、以下のことを行います。
   • 効率的なクエリと検索操作を容易にします。
   • Claudeが知識グラフを迅速に探索できるようにします。
   • リンクのトラバーサルを高速化するために関係情報を維持します。
   • 必要に応じてMarkdownファイルから自動的に再構築されます。
   • デフォルトでSQLiteを使用します。PostgreSQLや他のバックエンドを使用する場合は、ZETTELKASTEN_DATABASEを通じてSQLAlchemy URLを指定します。

システム外でMarkdownファイルを直接編集した場合は、zk_rebuild_indexツールを実行してデータベースを更新する必要があります。データベース自体はいつでも削除でき、Markdownファイルから再生成されます。

利用可能なMCPツール

すべてのツールは、より良い組織化のためにzk_で始まる名前が付けられています。

プロジェクト構造

zettelkasten-mcp/
├── src/
│   └── zettelkasten_mcp/
│       ├── models/       # データモデル
│       ├── storage/      # ストレージ層
│       ├── services/     # ビジネスロジック
│       └── server/       # MCPサーバの実装
├── data/
│   ├── notes/            # ノートの保存先（Markdownファイル）
│   └── db/               # インデックス用のデータベース
├── tests/                # テストスイート
├── .env.example          # 環境変数のテンプレート
└── 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 - すべてのテストに共通のフィクスチャ
├── 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 - ゼッテルサービスのテスト

🔧 技術詳細

このZettelkasten MCP Serverは、Zettelkasten知識管理手法を実装したMCPサーバです。Claudeやその他のMCP互換クライアントと連携して、原子的なノートの管理を行います。二重ストレージアーキテクチャを採用することで、データの保存と管理を効率的に行っています。また、同期的な操作モデルを使用することで、シンプルなアーキテクチャを実現しています。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

⚠️ 重要提示

このソフトウェアは実験的なものであり、いかなる保証も付与されていません。データの整合性を確保するための努力は行われていますが、バグが存在する可能性があり、データの損失や破損につながる可能性があります。常に定期的にノートをバックアップし、重要な情報でのテストには注意してください。

このMCPサーバはClaudeの支援を受けて作成されました。Claudeは、このプロジェクトの原子的な思考をまとめて、一貫した知識グラフに整理するのに役立ちました。Luhmannの紙ベースのシステムとは異なり、Claudeは90,000枚のインデックスカードを必要とせずに効果的に機能しました。

コードフォーマット用のpre-commit

コードスタイルを統一するために、このプロジェクトは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でプロジェクトを開くことでワークスペース設定を有効にします。必要に応じて拡張機能をインストールし、ウィンドウを再読み込みする必要があります。