mcp-zettel

Claude（または任意のMCPクライアント）にZettelkasten形式の永続的なメモリを与えましょう。

MCPサーバーは、アトミックで相互接続されたMarkdownノートの個人知識ベースを、Claude Desktop、Claude Code、Cursor、またはMCP互換クライアントに公開します。これを接続することで、アシスタントはノートを作成し、[[wiki-links]]で相互参照し、キーワードやタグで検索し、バックリンクを辿ることができるようになります。これにより、手動でコピー＆ペーストすることなく、セッションをまたいで耐久性のあるコンテキストを構築・利用できるようになります。

なぜこれが必要か

LLMとのチャットを開始するたびに、あなたがすでに決定したこと、書いたこと、学んだことに関するコンテキストはゼロから始まります。Zettelkastenメソッド（小さなアトミックなノート＋それらの間の明示的なリンク）は、LLMがアクセス可能なメモリとして非常に適しています。チャンクは自然に小さく、リンクによって関連性が明確になり、ストレージはあなた自身のディスク上のプレーンなMarkdownファイルだからです。

このMCPサーバーは、MCPツールを通じてその知識ベースをLLMクライアントに公開するため、モデルは以下のことが可能になります：

• 作成: 保持する価値のある決定や洞察を共有したときに、新しいノートを作成する

• 検索: 回答する前にトピックに関するノートを検索する（「Xについて何と決めたっけ？」）

• リンク: ノートを双方向にリンクしてグラフを構築する（「これは[[a3f2c9]]と矛盾する」）

• バックリンクを辿る: コンセプトに関連するすべてのものを見つける

あなたはディスク上にプレーンなMarkdownファイルを保持し、モデルはそれらへの構造化されたアクセス権を得ます。

Related MCP server: obsidian-pkm

クライアントでの表示

サーバーを接続すると、LLMは以下のようなことができます（クライアントには実際のツール呼び出しが表示されます）：

> What did I conclude about RAG chunk sizes?
[searches notes with query "rag chunk size"]
[reads 2 matching notes]
Based on your notes a3f2c9 ("RAG chunk sizing") and b7e412 ("Sentence-boundary
splitting"), you concluded: 800 chars with ~15% overlap, sentence-aligned.
You flagged that pure character chunking ([[2f00a1]]) hurt recall on your
arxiv set and moved away from it.

公開されているMCPツール

さらにMCPリソース：

• zettel://all — すべてのノートの1行インデックス

• zettel://{note_id} — 完全なレンダリング済みノート

• zettel://graph — v0.4. すべてのノートと[[wiki-link]]のMermaid図。Markdown+Mermaid対応クライアント（Claude Desktop、Obsidian、mdBookなど）でインラインレンダリングされます。

• zettel://graph/tag/{tag} — v0.4. 同じ図ですが、{tag}を持つノートとその直接の隣接ノードに限定されます。グラフ全体が大きすぎて読みにくくなった場合に便利です。

2つの検索ツール

キーワード検索は、用語を知っている場合に最適です。低コストでランキングが予測可能であり、完全一致は常に類似したものよりも優先されます。セマンティック検索は、クエリの文言がノートの文言と一致しない場合に有効です。例えば、ノートで「スロットリング」と呼んでいるものに対して「レート制限」と尋ねたり、ノートが「TTLチューニング」について書かれているのに「なぜキャッシュがコールドなのか」と尋ねたりする場合です。LLMは意味のある方を呼び出すことができ、ツールの説明がどちらを使うべきかを指示します。

埋め込みモデルはデフォルトでBAAI/bge-small-en-v1.5（384次元、約130MB、CPUのみ）を使用します。MCP_ZETTEL_EMBEDDING_MODELで上書き可能です。インデックスは書き込み後の最初のセマンティッククエリ時に遅延再構築されるため、初回のみ少し待機時間が発生しますが、その後はサーバープロセスの存続期間中メモリに保持されます。

インストール

git clone https://github.com/dhruvpatel1706/mcp-zettel.git
cd mcp-zettel
pip install -e .

Python 3.10以上が必要です。

セットアップ

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはOS上の同等のファイルを編集し、以下を追加します：

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server"
    }
  }
}

Claude Desktopを再起動します。これでzettelツールがモデルから利用可能になります。

Claude Code

claude mcp add zettel -- mcp-zettel-server

Cursor / Continue / その他のstdio MCPクライアント

クライアントでmcp-zettel-serverをコマンドとして指定します。サーバーはstdio経由でMCPと通信します。

カスタムストレージの場所

MCP_ZETTEL_ROOTを設定して、デフォルトの~/.mcp-zettelを上書きします：

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server",
      "env": { "MCP_ZETTEL_ROOT": "/Users/you/vault" }
    }
  }
}

CLIを直接使用する（MCPクライアント不要）

同じストアにプレーンなCLI経由でアクセスできます。LLMセッション外で知識ベースを検査、編集、またはシードしたいパワーユーザーに便利です。

mcp-zettel create "RAG chunk sizing" \
  --body "Settled on 800 chars, 15% overlap, sentence-aligned. See [[b7e412]]." \
  --tag rag --tag decisions

mcp-zettel list --tag rag
mcp-zettel search "sentence boundary"
mcp-zettel show a3f2c9
mcp-zettel backlinks a3f2c9

ディスク上のレイアウト

~/.mcp-zettel/
└── notes/
    ├── a3f2c9.md          ← one markdown file per note
    ├── b7e412.md          ← YAML frontmatter: title, tags, created_at, updated_at
    └── ...                ← body is plain markdown; [[id]] is a wiki-link

すべてのノートは単一のファイルです。つまり、バックアップが容易（git）、grepが容易、ロックインがないことを意味します。もしこのサーバーの使用をやめても、Markdownファイルのディレクトリはそのまま残ります。

設計上の選択

• データベースではなくファイル: ノートごとに1つのMarkdownファイルであるため、どのエディタでも編集でき、gitでバックアップでき、ツールなしで検査できます。ストアは単なる薄い接着剤です。

• スラッグ化されたタイトルではなく短い16進数ID: [[a3f2c9]]は安定しています。タイトルを変更しても、すべてのインバウンドリンクは解決されたままです。ファイル名ベースのスラッグよりも短いです。

• 双方向リンクは派生、保存はしない: バックリンクは、すべてのノートの本文をスキャンして[[target_id]]を探すことで、読み取り時に計算されます。整合性を保つための別のインデックスは不要です。この設計の規模（数千ノート以下）では些細なことです。

• タイトル/タグの重み付け検索: タイトルヒットは3倍、タグヒットは2倍、本文ヒットは1倍としてカウントされます。ノートのタイトルに「retrieval」とあれば、本文の途中で一度その単語が出てくるノートよりも、そのトピックに関するものであるという直感に一致します。

• 低レベルMCPではなくFastMCP: MCP Python SDKのデコレータベースのFastMCPインターフェースにより、ツールはPydantic型付き引数を持つ単なるPython関数となり、手動でのJSONスキーマ作成は不要です。

開発

pip install -e ".[dev]"
pytest
black --check src tests
isort --check-only --profile black src tests
flake8 src tests --max-line-length=100 --ignore=E501,W503,E203

CIはPython 3.10 / 3.11 / 3.12で実行されます。

MCPインスペクターを使用してサーバーを対話的に検査します：

npx @modelcontextprotocol/inspector mcp-zettel-server

プロンプトテンプレート (v0.3)

プロンプトメニューをサポートするMCPクライアント（Claude Desktop、Cursor）は、指示を再入力することなく一般的なZettelkastenの操作を行うための「正しい方法」をエンコードした4つのサーバーサイドテンプレートを利用できます：

これらは@mcp.prompt()で登録された文字列を返す関数です。文言をサーバーサイドに保持することで、Claude Desktop、Claude Code、Cursorのどこから呼び出しても同じ「distill」プロンプトが一貫して動作します。

ロードマップ

• [x] v0.2 — キーワード検索と並行した埋め込みベースのセマンティック検索

• [x] v0.3 — 一般的なノート操作のための@mcp.prompt()テンプレート

• [x] v0.4 — リンクのMermaid図を返すグラフビューリソース (zettel://graph)

• [ ] v0.5 — マルチデバイスアクセスのためのリモートStreamable HTTPトランスポート

ライセンス

MIT。LICENSEを参照してください。