Zettelkasten MCP Server

Zettelkasten MCP サーバー

Zettelkasten の知識管理手法を実装した Model Context Protocol（MCP）サーバーです。Claude やその他の MCP 互換クライアントを通じて、アトミックノートの作成、リンク、探索、統合を行えます。

Zettelkasten とは？

Zettelkasten メソッドは、ドイツの社会学者 Niklas Luhmann が開発した知識管理システムです。彼はこの手法を用いて、70 冊を超える書籍と数百本の記事を執筆しました。この手法は、次の 3 つの基本原則で構成されています。

1. アトミック性：各ノートには 1 つのアイデアだけが含まれ、知識の独立した単位となります。
2. 接続性：ノート同士をリンクして知識のネットワークを構築し、アイデア間に意味のある関係を持たせます。
3. 創発性：ネットワークが成長するにつれて、個々のノートを作成した時点では明らかでなかった新しいパターンや洞察が現れます。

Zettelkasten の手法が強力なのは、さまざまな方法で探索できるようになるためです。

• 垂直方向の探索：ある分野内のつながりをたどって、特定のトピックをさらに深く掘り下げます。
• 水平方向の探索：分野をまたぐリンクをたどり、異なる分野間にある予想外の関係を見つけます。

この構造では、ノートからノートへ思考の軌跡をたどることで、偶然の発見が促されます。また、固有の識別子を通じて、すべての情報に簡単にアクセスできます。Luhmann はこのシステムを「第二の脳」または「対話のパートナー」と呼びました。このデジタル実装は、最新技術を通じて同様のメリットを提供することを目指しています。

機能

• タイムスタンプベースの固有 ID を持つアトミックノートを作成
• ノートを双方向にリンクしてナレッジグラフを構築
• ノートにタグを付けてカテゴリ別に整理
• 内容、タグ、リンクからノートを検索
• 人間が読みやすく編集しやすい Markdown 形式を使用
• MCP を通じて Claude と連携し、AI による知識管理を実現
• デュアルストレージアーキテクチャ（下記参照）
• アーキテクチャを簡素化する同期操作モデル

例

• 知識の作成：Zettelkasten メソッド自体についての小さな Zettelkasten ナレッジネットワーク

ノートの種類

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 ディレクトリには、開始に必要なファイルが含まれています。

システムプロンプト

次のいずれかを選択します。

• 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

プロジェクトのナレッジ（開発者向け）

開発者およびコントリビューター向け：

• 例 - シンプルなMCPサーバー.md
• MCP Python SDK-README.md
• llms-full.txt

注：必要に応じて、repomixなどのツールを使ってソースコードを含めることもできます。

ストレージアーキテクチャ

このシステムは、2種類のストレージを組み合わせて使用します。

1. Markdownファイル：すべてのノートは、メタデータ用のYAMLフロントマターを含む、人が読めるMarkdownファイルとして保存されます。これらのファイルが信頼できる唯一の情報源であり、次のことが可能です。

   • 任意のテキストエディターで直接編集する
   • バージョン管理（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 Desktopへの接続

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

{
  "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 は、このプロジェクトの断片的なアイデアを、まとまりのあるナレッジグラフへと整理するのを支援してくれました。優れたツェッテルカステンシステムのように、Claude は、そうでなければ孤立したままだったかもしれないアイデア同士を結び付けました。ただし、ルーマンの紙ベースのシステムとは異なり、効果を発揮するために Claude が 90,000 枚ものインデックスカードを必要とすることはありませんでした。

ライセンス

MIT ライセンス