obsidian-cli-mcp

実行中のObsidianボールトを、公式のObsidian CLI（Obsidian 1.12以降）を介してClaudeや他のMCPクライアントから完全に制御できるMCPサーバーです。高速な直接ファイルシステム読み取りも、正確性が許す範囲で行います。

things-for-mac-mcp の仲間プロジェクトです。

他のMCPサーバーと何が違うのか？

ほとんどのObsidian MCPサーバーは、コミュニティ製のRESTプラグインと通信するか、ボールトフォルダーを直接読み取ります。前者はプラグインのインストールと信頼が必要です。後者は、ファイルを移動または名前変更した瞬間にウィキリンクを静かに壊します。なぜなら、そのファイルを指すすべてのリンク、エイリアス、埋め込みを知っているのはObsidianだけだからです。

このサーバーは、すべての操作を機能ごとにルーティングします。

アーキテクチャは姉妹プロジェクトと完全に一致します。

分割の背後にあるルール：バルク読み取りはスループットが必要なためファイルシステムに送られ、移動、名前変更、削除、リンク解決やアプリ状態に依存する操作はすべてCLIを通じて行われます。ファイルシステムアダプターは構造的にボールトを変更できず、書き込み関数を一切エクスポートしません。

要件

• macOS、Windows、またはLinuxデスクトップで Obsidian 1.12以降

• Obsidian CLIが有効になっていること：Obsidian、設定、一般、コマンドラインインターフェース

• Obsidianが実行中である必要があります。 CLIはアプリのクライアントであり、スタンドアロンバイナリではありません。デスクトップのみで、モバイルはサポートされていません。

• Node.js 18以降

インストール

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

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

Claude（デスクトップ／コード）

claude_desktop_config.json（Claude Desktop）に追加するか、claude mcp add（Claude Code）を実行します。

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

nodeの絶対パスを使用し、単なる単語は使用しないでください。 GUIで起動されたアプリはシェルのPATHを継承しないため、多くのクライアントで"command": "node"は静かに失敗します。which nodeで自分のパスを見つけてください。

複数のボールトがある場合はOBSIDIAN_VAULTを設定してください。 そうしないと、CLIは最後にフォーカスされたボールトをターゲットにしますが、これは自動化された書き込みには最悪の特性です。単一ボールトの場合、サーバーは起動時に自動的に固定します。

設定

ガードレール

バイナリが起動される前に強制される3つのティア：

• ティア1、自由： 読み取り、検索、追加書き込み（create_note、append_note、append_daily、set_property、update_task、capture）。

• ティア2、ツールコールでconfirm: trueが必要： delete_note、move_note、rename_note、remove_property、run_obsidian_command、およびパススルー経由：history:restore、publish:*、plugin:enable/disable/reload、theme:*、snippet:*、sync、sync:restore、reload、template:insert、workspace:save/delete。overwriteまたはpermanentフラグを持つ呼び出しもティア2に引き上げられます。

• ティア3、サーバーがOBSIDIAN_MCP_ALLOW_DANGEROUS=1で実行されていない限りブロック： eval、restart、plugin:install、plugin:uninstall、plugins:restrict、devtools、dev:cdp、dev:debug、dev:mobile、およびpermanent: true付きのdelete_note。

これらが何であるかについて正直に述べておきます。ティア2は偶発的な呼び出しに対する速度バンプであり、セキュリティではありません。呼び出し元のモデルは自分でconfirm: trueを設定できます。ティア3は真の境界です。サーバー環境を設定する人だけがそれを解除できるからです。重要なボールトに自律エージェントを向ける場合は、OBSIDIAN_MCP_READONLY=1で実行してください。これは、ティアに関係なく、ディスパッチ前にすべての変更コマンドを拒否します。

リンクセーフな移動と名前変更

このプロジェクトで最も重要なルール：ファイルはファイルシステムを通じて移動、名前変更、削除されることはありません。 Obsidianは操作を実行するときにボールト内のすべてのウィキリンクを更新します。単純なmvではそれを行いません。

変更前：Projects/Roadmap.mdが3つのノートからリンクされている場合：

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

move_noteをto: "Archive/2026 Roadmap.md"で実行した後：

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

3つのリンクすべてが、見出しアンカーとエイリアスを含めて更新されました。これはObsidianが移動を行ったためです。ファイルシステムでの移動では、3つのリンクが壊れ、エラーも発生しません。

なぜハイブリッドなのか？パフォーマンスの理論的根拠

CLI呼び出しはすべて、実行中のObsidianアプリを通じた1回の完全なIPCラウンドトリップです。これは正確ですが遅いです。obsidian readで2000のノートを読むことは2000回のラウンドトリップとなり、数分の壁時計時間がかかります。ディスクから読むことは1回のディレクトリウォークで、どんなSSDでも1秒未満です。

そのため、バルク読み取り（検索、リスト、タグとプロパティのスキャン、エクスポート、ダイジェスト）はファイルシステムにヒットし、CLIはObsidianだけが答えられるもの（リンク、エイリアス、Bases、テンプレート、アプリ状態）とすべての書き込みのために予約されています。自分のボールトで比較するには、パススルーobsidian_cliを["search", "query=..."]で使用してsearch_notesを時間測定してみてください。

トラブルシューティング

「Obsidianが実行されていません。」 最も一般的な失敗。CLIはアプリが開いて完全に読み込まれている必要があります。Obsidianを起動して再試行してください。

「Obsidian CLIバイナリが見つかりません。」 Obsidianの設定、一般、コマンドラインインターフェースでCLIを有効にするか、OBSIDIAN_BINでバイナリを指定してください。

最初のコマンドでタイムアウト。 コールドスタートのObsidianは20秒のデフォルトを超える可能性があります。OBSIDIAN_MCP_TIMEOUTを引き上げてください。

ノートが欠落していると読み取られる、またはサーバーが頻繁にCLIにフォールバックする。 ボールトがiCloudにあり「Macストレージを最適化」がオンの場合、退避されたファイルは.name.icloudスタブとしてのみ存在します。サーバーはこれらを検出し、空のノートを報告する代わりにObsidianを通じて読み取り、再ダウンロードします。バルクスキャンは退避されたファイルをスキップし、その出力でその旨を伝えます。

書き込みが間違ったボールトに届く。 複数のボールトがあり、OBSIDIAN_VAULTが設定されていません。サーバーは起動時にstderrでこれについて警告します。1つを固定してください。

ツールがクライアントに表示されない。 クライアントのMCPログを確認し、上記の絶対nodeパスの問題を確認してください。

最新情報の入手

git pull && npm install && npm run build

サーバーは起動時に更新を確認し、最大24時間に1回、結果を~/.config/obsidian-cli-mcp/update-check.jsonにキャッシュします。オフライン時は静かに失敗し、新しいバージョンが存在する場合はstderrに1行出力します。

ツール（全39）

読み取りツール（18）

書き込みツール（16）

すべての書き込みはCLIを通じて行われます。それぞれに明示的なfileまたはpathターゲットが必要で、現在アクティブなファイルにフォールスルーすることはありません。

run_obsidian_command はサーバーの中で最も広い扉です。コミュニティプラグインが登録したものを含む、すべてのコマンドパレットアクションに到達します。意図的に公開されており、階層2で制限されています。

ワークフローツール（4）

エスケープハッチ（1）

MCPリソース

リソースのクライアントサポートはさまざまで、Claude Desktopは現在これらを表示しません。

MCPプロンプト

アーキテクチャ

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

テストは、完全なargvをスキャンし、失敗、ハング、または過大な出力を生成するように指示できるスタブバイナリに対して実行されます。そのため、Obsidianがインストールされていなくてもスイート全体が合格します。

npm test

サポート

問題や機能リクエスト: GitHub issues。

作者のその他の作品

• things-for-mac-mcp、Things 3用の姉妹MCPサーバー

ライセンス

MIT