obsidian-mcp

公式のObsidian CLIをラップするMCPサーバーです。LLMエージェントが実行中のObsidianインスタンスを操作し、ノートの読み書き、検索、フロントマターの管理、リンクのナビゲーション、プラグインの実行などを行えます。

このサーバーは軽量かつ包括的なラッパーです。すべてのツールはobsidian CLIコマンドと1対1で対応しています。

前提条件

1. Obsidianが起動していること。 CLIはIPC経由で実行中のアプリと通信するため、ディスク上のボルトを直接読み取るわけではありません。

2. CLIバイナリを登録すること。 Obsidianの「設定」→「一般」→「コマンドラインインターフェース」→「CLIを登録」から行います。ObsidianがPATHにobsidianを追加します。

3. 確認: obsidian versionを実行し、CLIのバージョンが表示されることを確認してください。

インストール

自分でビルドする場合と、npmから公開済みのバージョンを取得する場合の2つの方法があります。

オプションA — クローンしてビルド（今すぐ利用可能）

リポジトリをクローンしてローカルでビルドし、Claude Codeにビルド済みファイルを指定します：

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

Claude Codeに登録します（1コマンド）：

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s userはユーザーアカウント全体に登録します。リポジトリの.mcp.jsonにコミットする場合は-s projectを、現在のプロジェクトのみに適用する場合は-s local（デフォルト）を使用してください。

または、.mcp.jsonに手動で記述します：

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

オプションB — npmからインストール（ビルド不要）

前提条件: パッケージがすでにnpmに公開されている必要があります。メンテナーがnpm publishで一度公開すれば、以降のユーザーはnpx経由で自動的に利用できます。このリポジトリをフォークし、自分のスコープでこのフローを行いたい場合は、package.jsonのnameを@<あなたのnpmユーザー名>/obsidian-mcpに変更してからnpm publishしてください。

公開後は、クローンやビルドは不要です：

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

または、.mcp.json / Claude Desktopのclaude_desktop_config.jsonに記述します：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

CLIパスのオーバーライド

obsidianがPATHにない場合は、OBSIDIAN_CLI環境変数を設定してください。どちらのインストール方法でも動作します：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

ツール

ボルトとファイル

フロントマターのプロパティ

検索

タグとリンク

デイリーノート

プラグイン

開発者 / 高度な機能

メタ

規約

• ノートの指定 — ファイルを対象とするツールは以下を受け付けます：

  • file — ウィキリンク形式のノート名（例: "My Note"）、または

  • path — ボルト相対のファイルパス（例: "Folder/My Note.md"）。

• マルチボルト設定 — すべてのツールはオプションのvaultパラメータを受け付けます。省略された場合は、最後にフォーカスされたボルトが使用されます。

• 出力形式 — リスト/検索/メタデータツールは、機械的な解析を容易にするためデフォルトでJSONを返します。

機密操作とユーザー確認

以下のツールは、ユーザー確認ステップを必要とします：

確認の仕組み：

1. MCP elicitation（推奨）。 接続先のクライアントがelicitation機能をサポートしている場合（Claude Codeは対応）、サーバーはelicitation/createリクエストを送信し、クライアントはアクションとターゲットを明示した「実行しますか？」というプロンプトを表示します。accept + confirm: trueの場合のみ実行されます。

2. 明示的なconfirm: trueパラメータ。 すべての機密ツールの入力スキーマには、オプションのconfirm: booleanが含まれています。confirm: trueを渡すとプロンプトをスキップします。これは呼び出し元がすでにユーザーの承認を得ている場合にのみ使用してください。

3. 拒否時のフォールバック。 クライアントがelicitationをサポートしておらず、confirm: trueも提供されていない場合、ツールはアクション名を明示し、confirm: trueを付けて再試行するよう指示するisError結果を返します。

バッチ / 自動化のためのバイパス

OBSIDIAN_MCP_AUTO_CONFIRM=1

この環境変数を（MCPクライアントのenvブロック内で）設定すると、すべての確認プロンプトをスキップします。完全に信頼できる自動化コンテキストでのみ使用してください。

長いコンテンツとargvの制限

Obsidian CLIは（現時点では）標準入力やファイルからのパラメータ読み込みをサポートしておらず、すべての値がコマンドライン経由で渡されます。これはプラットフォームの制限に抵触します：

安全のため、サーバーは長い書き込みを自動的にチャンク分割します：

可能な場合は行境界で分割し、長すぎる単一行はUTF-8安全な文字境界でフォールバックします。再構築されたコンテンツは元のデータとバイト単位で同一です。

呼び出しごとのバイトしきい値を設定します（デフォルト：Windowsは6,000、その他は100,000）：

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

マルチチャンク書き込みの途中でチャンクが失敗した場合、サーバーはどのチャンクまでがディスクに書き込まれたかを明示するisErrorを返し、呼び出し元が復旧できるようにします。

開発

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

仕組み

runObsidian() (src/exec.ts) は引数をシェルクォートし、child_process.exec経由でobsidianバイナリを呼び出し、標準出力を解析します。ほとんどの読み取り系ツールはformat=jsonを要求します。結果は、構造化されたツール出力を消費するクライアント向けにstructuredContentに解析されますが、contentにはテキスト表現も返されます。

ツールレジストリはsrc/tools.tsにあります。新しいコマンドを追加するには、そこに1行追加するだけです。

リファレンス

• Obsidian CLI: https://obsidian.md/help/cli

• MCP spec: https://modelcontextprotocol.io