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/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

このコマンドは stdio 上で MCP を話し、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/obsidian-cli-mcp@0.4.1",
        "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 を参照してください。

ツールサーフェス

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

• 読み取り: 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。

すべての変更ツールは 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