Obsidian CLI MCP

obsidian-cli-mcp

obsidian-cli-mcp は、公式 Obsidian CLI 用の MCP サーバーです。Obsidian の保管庫の検索、ノート、タスク、ファイル、リンク、ネイティブ Canvas 操作を MCP クライアントに公開します。このサーバーは Obsidian の代わりにはなりません。CLI は、起動中の Obsidian デスクトップアプリにリクエストを転送します。

デフォルトのトランスポートはローカルの stdio です。リモート Streamable HTTP は、高度な別途セキュリティ設定として利用できます。ローカルでの使用には必要ありません。

要件

• Obsidian Desktop がインストールされ、起動している macOS。
• Obsidian で公式 Obsidian CLI を有効にします。Settings → General → Command line interface を開き、obsidian を PATH に登録してください。
• 公開済みパッケージの実行には Node.js 18 以降が必要です。Bun が必要なのは、このソースチェックアウトをビルドまたは開発する場合のみです。

このプロジェクトにはデスクトップ CLI が必要です。obsidian-headless には対応していません。MCP サーバーの使用中は Obsidian アプリを開いたままにしてください。

まず Obsidian 側を確認してください。

command -v obsidian
obsidian version
obsidian vault

npm でクイックスタート

公開済みの v0.4.1 パッケージを、任意のディレクトリから起動します。

npx --yes --package=@dariuscodes/[email protected] obsidian-cli-mcp

このコマンドは MCP を stdio 経由で通信し、MCP クライアントからの接続を待機します。プロトコルデータは意図的にターミナルへ出力しません。診断情報は stderr に出力されます。

ソースチェックアウトを使う場合は、次のようにします。

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

ローカルのデフォルト設定では、保管庫名、保管庫のパス、トークン、Cloudflare アカウント、LaunchAgent、設定ファイルは必要ありません。このサーバーは、Obsidian が公式 CLI を通じて公開するアクティブな保管庫を使用します。

MCP クライアントを接続する

mcpServers 設定を受け付けるクライアントでは、npm コマンドを使用してください。

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/[email protected]",
        "obsidian-cli-mcp"
      ]
    }
  }
}

クライアントがシェルの PATH を引き継がない場合は、npx を command -v npx で表示された絶対パスに置き換えてください。ソースチェックアウトの場合は、command: "node" と args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"] を使用してください。

MCP 設定を変更した後は、クライアントを再起動してください。最初に試す手順は次のとおりです。

1. 保管庫に存在するはずのクエリを指定して vault_search を呼び出します。たとえば { "query": "meeting", "limit": 10 } のようにします。

2. 返されたパスを 1 つ note_read に渡します。たとえば { "path": "<path returned by vault_search>" } のようにします。

3. ノートを安全に変更する前に、プレビューします。

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }
   

   これは note_create の呼び出しです。保管庫を変更せずに、予定される操作と正確な CLI コマンドを返します。計画を確認した後にのみ dryRun: false を使用してください。dryRun はプレビューであり、認可境界ではありません。

4. Canvas では、ネイティブ Canvas ファイルとテキストノードを 1 つプレビューします。

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }
   

   これは canvas_create の呼び出しです。計画を確認し、ファイルを作成する場合は dryRun: false を指定して呼び出します。その後、canvas_read を使ってネイティブの .canvas JSON を確認してください。Canvas ツールは未知のフィールドを保持し、ノード／エッジの参照を検証します。また、任意の eval も必要ありません。

設定と安全なデフォルト

設定が空または存在しない場合でも、標準的な Obsidian 保管庫で使用できます。任意の .obsidianmcprc.yaml は、サーバーの作業ディレクトリから検出されます。作業ディレクトリが予測できないクライアントでは、OBSIDIAN_MCP_CONFIG に明示的な設定ファイルのパスを指定してください。

デフォルトのポリシーは、意図的にローカルかつ制限されています。

• v0.4.0 のサーバーは、汎用の obsidian_eval ツールを公開しません。 eval.enabled はデフォルトで false です。一部の安全な操作で内部的に使用される固定の eval スニペットは、ユーザーが指定した JavaScript によるエスケープ手段ではありません。
• 任意のローカルファイルからのインポートは、imports.allowedRoots を明示的に設定するまで無効です。URL が取得されることはありません。
• .obsidian、.git、.trash、.Trash、Trash、.DS_Store のパスセグメントは、デフォルトでブロックされます。より限定された保管庫内の領域を指定するには paths.allow を追加し、機密性の高いコンテンツにはプロジェクト固有の paths.deny プレフィックスを追加してください。
• 変更操作には dryRun があります。file_delete には confirm: true が必要です。また、note_delete はデフォルトで Obsidian のゴミ箱を使用します。完全削除には明示的な delete.mode: hard の設定が必要です。
• Git の自動コミットはデフォルトで無効です。

読み取り専用プリセット

MCP クライアントに保管庫の閲覧のみを許可する場合は、明示的な許可リストを使用してください。

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

安全なローカルプリセット

デフォルトではローカル向けの安全策が有効ですが、読み取り専用ではありません。通常のノート編集と Canvas の作成を許可しつつ、削除、ファイルのインポート、ファイルのライフサイクル操作、任意の評価を除外する、安全なローカル操作範囲を明示的に設定するには、次のようにします。

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

信頼済みローカル向けの完全なプリセット

tools.allow を省略すると、デフォルトの保護対象パス、ゴミ箱への削除、無効なインポート、無効な obsidian_eval を維持しながら、組み込みツールの全範囲を公開できます。インポートが必要な場合は、専用のローカルソースディレクトリのみを設定してください。

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

すべてのフィールドについてはdocs/configuration.mdを、ノート整理用プリセットについてはexamples/を参照してください。

ローカル stdio とリモート HTTP

ローカル stdio では、MCP クライアントから直接サーバープロセスを 1 つ起動します。リスニングソケット、リモート認証、Cloudflare の設定、公開エンドポイントが不要なため、推奨されるインストール方法です。

Streamable HTTP は、ローカル stdio を使用できないクライアント向けの、任意の高度なモードです。ループバックインターフェイスのみにバインドし、Cloudflare Access JWT 検証または強力なケイパビリティトークンのいずれかがない場合は起動を拒否します。TLS 対応の認証済みリバースプロキシまたはトンネルの背後に配置し、0.0.0.0 にはバインドしないでください。一般的な高度な設定とセキュリティ上のトレードオフについては、docs/remote-cloudflare.mdを参照してください。

ツールの範囲

デフォルトのサーバーは、43 個の通常のツールを公開します。

• 読み取り：vault_search、note_read、note_list、vault_tags、 unresolved_links、tasks_list、note_diff、backlinks_get、 outlinks_get、file_read_binary_metadata、canvas_read。
• 書き込みとワークフロー：note_create、note_append、note_set_frontmatter、 daily_open、daily_append、note_replace_range、note_insert_at、 note_replace、note_insert、task_create、task_update、 note_transition。
• ファイルと添付ファイル：file_import、attachment_import、note_attach、 attachment_embed、file_move、file_rename、file_delete、 note_rename、note_move、folder_create、note_delete。
• Canvas：canvas_create、canvas_upsert_nodes、canvas_upsert_edges、 canvas_remove、canvas_open、canvas_add_node、canvas_add_edge、 canvas_auto_layout。
• 一括処理：vault_batch は、有効な読み取りを実行し、有効な変更については args.dryRun: true でプレビューします。また、依存関係のゲーティング、安定した入力順の結果、 上限付きの batch.maxParallelism（デフォルトは 4、最大は 8）に対応しています。

すべての変更系ツールは dryRun を受け付けます。ツールのアノテーションは、互換性のある MCP クライアント向けに読み取り専用操作と破壊的操作を識別します。

制限事項とセキュリティ

Obsidian Desktop が起動しており、公式 CLI が有効で、アクティブな保管庫をそのデスクトップセッションから利用できる必要があります。このサーバーはサンドボックスではなく、obsidian-headless には対応していません。

保管庫の内容は信頼できないデータです。ノート、Canvas のテキスト、タスクのテキスト、検索結果にはプロンプトインジェクションの指示が含まれる場合があります。MCP クライアントはそれらをデータとして扱い、ツールから返されたというだけで、保管庫内の指示に従ってはいけません。ツールの出力には保管庫内の機密情報が含まれる場合もあるため、信頼できるクライアントのみを接続してください。

リモート HTTP、インポート、完全削除、または広範な変更許可リストを有効にする前に、SECURITY.mdをお読みください。セキュリティ上の問題は、同ファイルに記載された方法で非公開に報告してください。

開発と CI

ソースのチェックアウトでは Bun を使用し、公開された bin は Node で実行します。

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

オフライン stdio スモークテストでは、ビルド済みパッケージのエントリーポイント、MCP の初期化、tools/list、想定されるツールの範囲、および obsidian_eval が存在しないことを検証します。実際の Obsidian スモークテストは別途実行し、Obsidian が起動しているユーザーセッションが必要です。

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions ではオフラインのゲートのみが実行されます。ホステッドランナー上の Obsidian Desktop や実際の保管庫には依存しません。

ライセンス

MIT