obsidian-mcp-server

Obsidian学習Vault用のMCPサーバー（Model Context Protocol）です。 Claudeにノート検索、ノート内容、Decks形式のフラッシュカード作成、Lerntrackerプラグインの学習計画へのアクセスを提供します。

Python、MCP SDK 2.x、stdioトランスポート。

目的

これまで、ロジックは2つのObsidianプラグインで実行されていました：

• Decks（外部プラグイン）はフラッシュカードをレンダリングしますが、作成はしません。カードは手書きでした。

• Lerntracker（自作プラグイン）は学習進捗と学習計画を管理しますが、教材を自動的に日々に割り当てることは意図的にしていません。

このサーバーは両方のギャップを埋めます：Claudeは既存のファイル形式でカードを直接作成でき、Lerntrackerのdata.jsonに書き戻される学習計画を計算できます。

Related MCP server: Nexus MCP for Obsidian

インストール

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

設定

両方のパスは環境変数から取得されます。ハードコードはありません。

VaultパスのデフォルトはiCloud同期のObsidianに適しています。別のセットアップの場合は、OBSIDIAN_VAULT_PATHを設定するだけで十分です。

Lerntrackerパスは個別に設定可能です。Obsidian Vaultは入れ子になる可能性があるためです。サブフォルダーに別のVaultがある場合、それには独自のdata.jsonがあります。デフォルトはメインVaultのものを指します。

ツール

すべてのスキーマはSDKによって型ヒントとdocstringから生成されます。コードには手書きのJSONスキーマはありません。

フラッシュカード形式

create_flashcardは、Vault内の既存のカードが使用する形式（ヘッダーパラグラフ）を正確に書き込み、ソースへのウィキリンクを追加します：

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

ターゲットファイルはソースノートのコースフォルダーから決まります。deckはファイル名を上書きします。ファイルが存在しない場合は、tags: [decks] で作成されます。同一の表面を持つカードは、重複して作成される代わりにスキップされます。

Decksの学習状態はMarkdownファイルではなくSQLiteデータベースにあります。サーバーはそれに触れません。FSRS履歴は変更されません。

generate_summaryが自分で要約しない理由

サーバーには言語モデルがありません。ノートを構造化して返します（概要、指標、全文）。要約はクライアント側、つまりClaude Desktopのモデルが書きます。その後、save_summaryで保存されます。これは通常のMCPの役割分担です：サーバーはコンテキストを提供しアクションを実行し、モデルが文章を作成します。

代わりにサーバーが自分で要約するには、Anthropic APIを呼び出し、独自のAPIキーが必要になります。

学習計画ロジック

generate_study_planは、未完了の各サブトピックを具体的な日付に割り当てます：

1. コースは試験日で並べ替えられます。最も早い試験が最初です。

2. 学習終了日 = examDate − bufferDays。バッファ日は復習のために空けておきます。

3. 学習日はsettings.weeklyHoursから取得されます（0 = 日曜日 … 6 = 土曜日）。0時間の日とすべてのblockedDatesはスキップされます。

4. 各サブトピックはhours_per_subtopic（デフォルト1.5時間）を消費し、残り容量のある最も早い日に配置されます。1日に収まらない場合は、複数日に分割されます。プラグインは複数のdatesをサポートしています。

5. 既に完了したサブトピックと、既存のdatesを持つものは変更されません。

6. 学習終了日までに収まらないものは、黙って破棄されるのではなく警告として報告されます。

各書き込み操作の前に、ファイルの隣にバックアップ（data.backup-<Zeitstempel>.json）が作成されます。書き込みは一時ファイルを介して原子的に行われます。dry_run=Trueは計画のみを表示します。

Obsidianで書き込んだ後、プラグインを再読み込みするためにCmd+Rを押してください。

リソース

テンプレートは意図的に{path}ではなく{+path}（予約拡張）を使用しています。通常のテンプレート変数はスラッシュに一致しません。{path}ではサブフォルダー内のノートは静かに見つからず、Vault内のほぼすべてのノートはコースフォルダーにあります。

MCP Inspectorでローカルテスト

InspectorはSDKのCLIから起動され、ツールとリソースを個別に呼び出せるWebインターフェースを開きます。npx（Node.js）とuvが必要です。

source .venv/bin/activate && mcp dev main.py

コマンドはhttp://localhost:6274のようなURLを出力します（セッショントークンが付加されます）。ブラウザで開き、左側のConnectをクリックします。次に：

• ツールタブ → List Tools → ツールを選択し、引数を入力してRun Tool

• リソースタブ → List Resources → vault://structureをクリック

• テンプレート化されたリソースの場合は、note://<Kursordner>/Flashcards/<Datei>.mdのパターンでURIを直接入力します

異なるVaultを使用する場合：

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

書き込みツールを試すには、使い捨てVaultが便利です：

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

Claude Desktopへの接続

設定ファイル：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

重要：絶対パスを使用してください。~と$HOMEはここでは展開されません。commandにはvenvからのPythonを指定してください。Claude Desktopは有効化された環境なしでサーバーを起動するため、単なる"python3"ではmcpパッケージが見つかりません。

ファイルが既に存在する場合は、既存のmcpServersオブジェクトに"obsidian-vault"エントリを追加するだけです。その後、Claude Desktopを完全に終了して再起動します。サーバーは入力フィールドのツールメニューに表示されます。

セキュリティ

ツールまたはリソース呼び出しからのすべてのパスはVaultに対して検証されます。絶対パスと..トラバーサルは拒否され、解決されたターゲットはOBSIDIAN_VAULT_PATH内にある必要があります。.obsidian、.git、.trash、.claude、node_modulesは検索と構造リストから除外されます。プラグインバンドルが結果を圧倒するのを防ぐためです。

save_summaryは既存のファイルを上書きせず、create_flashcardは重複カードを作成せず、generate_study_planは書き込む前にdata.jsonをバックアップします。

テスト済み

mcp 2.0.0、Python 3.14に対して：ツールスキーマ、リソーステンプレート、実際のClientSessionとのstdioハンドシェイク、パスガード、および使い捨てVaultに対する書き込みツール（複数日分割、ブロックされた日、0時間の曜日、オーバーフローケースを含む）をテストしました。

ライセンス

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