Obsidian MCP Server

Obsidian MCP Server とは？

この Obsidian MCP サーバー（mcp-obsidian、作者 Markus Pfundstein）は、Local REST API コミュニティプラグインを介して、Claude などの MCP クライアントが Obsidian の保管庫（vault）にあるノートを一覧・読み取り・検索・書き込み・削除できるようにするオープンソースの Python サーバーです。

コミュニティプロジェクトで、Obsidian 公式の製品ではありません。サーバーが保管庫のファイルに直接触れることはなく、すべての操作は Obsidian アプリ内で動く Obsidian Local REST API プラグインを通して行われます。そのため、利用中は Obsidian を開いておく必要があります。PyPI で mcp-obsidian として公開されており、MIT ライセンスで、uvx で実行します。

Obsidian MCP Server の使い方

前提条件：

• Local REST API コミュニティプラグインをインストールして有効にした Obsidian。プラグインの設定から API キーをコピーします。
• uv（uvx 用）と Python 3.11 以降。

環境変数：

• OBSIDIAN_API_KEY：Local REST API プラグインのキー（必須）
• OBSIDIAN_HOST：デフォルトは 127.0.0.1
• OBSIDIAN_PORT：デフォルトは 27124

これらは MCP サーバーの設定（推奨）か、作業ディレクトリの .env ファイルで指定します。

Claude Desktop

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

Claude が uvx を見つけられない場合は、which uvx を実行し、そのフルパスを command に指定します。

Claude Code、Cursor、VS Code

README に記載されているのは Claude Desktop だけです。標準的な stdio サーバーなので、ほかのクライアントでも同じ env の値で uvx mcp-obsidian コマンドを実行できます（例：.cursor/mcp.json や .vscode/mcp.json）。Claude Code では、この 3 つの変数を設定して uvx mcp-obsidian を起動する stdio サーバーとして追加します。

Docker

uv や Python をインストールしたくない場合は、.env.example を .env にコピーし、docker compose build を実行してから、クライアントをコンテナに向けます。MCP には stdin の接続が必要で TTY は使えないため、up ではなく run --rm -T を使います。

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "docker",
      "args": ["compose", "-f", "<dir_to>/mcp-obsidian/docker-compose.yml", "run", "--rm", "-T", "mcp-obsidian"]
    }
  }
}

コンテナ内では OBSIDIAN_HOST のデフォルトが host.docker.internal になっており、手元のマシンの Obsidian に到達できます。

Obsidian MCP Server の主な機能

• 保管庫の閲覧：ルートや任意のフォルダーを一覧表示。
• ノートを 1 件ずつ、または複数件まとめて読み取り（一括読み取りでは出力を連結）。
• 前後の文脈付きのシンプルなテキスト検索に加え、高度な JsonLogic クエリとタグ検索。
• 精密な編集：見出し、ブロック参照、frontmatter のフィールドを基準にした挿入や、ファイル末尾への追記。
• ファイルの作成・全体の上書き、ファイルやフォルダーの削除（明示的な確認フラグが必要）。
• 定期ノート対応：現在のデイリー・ウィークリー・マンスリー・クォータリー・イヤリーノートや、最近の定期ノートを取得。
• 最近変更されたファイルや frontmatter の取得。
• ローカル前提の設計：ノートは手元のマシンに残り、プラグインのローカル API 経由でのみアクセス。

Obsidian MCP Server のツール

現在のソースは 15 のツールを登録しており、すべて obsidian_ で始まります。mcp.so のページと README に載っているのは最初の 7 つです。

• ナビゲーションと読み取り：obsidian_list_files_in_vault、obsidian_list_files_in_dir、obsidian_get_file_contents、obsidian_batch_get_file_contents。
• 検索：obsidian_simple_search（文脈付きのテキスト一致）、obsidian_complex_search（パスへの glob パターンなどを使う JsonLogic クエリ）、obsidian_search_by_tag。
• 書き込み：obsidian_append_content、obsidian_patch_content（見出し・ブロック・frontmatter を対象に append、prepend、replace）、obsidian_put_content（ファイル全体を置き換え）。
• 削除：obsidian_delete_file には confirm: true が必要です。
• メタデータと定期ノート：obsidian_get_frontmatter、obsidian_get_periodic_note、obsidian_get_recent_periodic_notes、obsidian_get_recent_changes。

Obsidian MCP Server のユースケース

README では、Claude が確実にツールを呼び出すよう、最初に Obsidian を使うよう指示することを勧めています。

• 会議を振り返る：「直近のアーキテクチャ会議のノートを取得して要約して。」
• 保管庫全体を調べる：「Azure CosmosDb に言及しているファイルをすべて探し、どんな文脈で触れられているか簡単に説明して。」
• 結果を書き戻す：「前回の会議メモを要約して新しいノート 'summary meeting.md' に保存し、メールで送れるよう導入文も付けて。」
• 日々の振り返り：「今日のデイリーノートを開き、Tasks 見出しの下に最優先の 3 項目を追加して。」
• 週次の整理：「今週変更したノートを一覧にし、まだ下書きのものにタグを付けて。」

Obsidian MCP Server と代替ツールの比較

Obsidian には公式の MCP サーバーがないため、選択肢はすべてコミュニティ製です。mcp-obsidian は Local REST API プラグインを介して動作するため、見出し単位のパッチ、定期ノート、JsonLogic 検索が使えます。その代わり、Obsidian を起動しておく必要があります。保管庫のフォルダーに汎用の Filesystem MCP Server を向ければ Obsidian なしでも使えますが、扱えるのはファイルだけで、frontmatter や定期ノートといった Obsidian の概念は理解しません。ほかのノートアプリなら Apple Notes MCP や Notion MCP Server を参照してください。

Obsidian MCP Server のトラブルシューティング

• AttributeError: 'Server' object has no attribute 'list_tools' でクラッシュする：このサーバーには mcp Python SDK 1.x（>=1.1.0,<2.0.0）が必要で、mcp>=2.0 を入れると動きません。uvx mcp-obsidian でバージョン固定済みのパッケージを使ってください。
• Claude がサーバーを起動できない：Claude が uv/uvx を見つけられないことがあります。設定に which uvx で得たフルパスを指定します。
• 接続拒否やタイムアウト：Obsidian が開いていること、Local REST API プラグインが有効なこと、OBSIDIAN_HOST/OBSIDIAN_PORT がプラグインと一致していること（デフォルトは 127.0.0.1:27124）を確認します。
• Docker コンテナが終了する、または止まる：MCP は stdin で通信するため、docker compose up ではなく docker compose run --rm -T で実行します。
• デバッグ：MCP Inspector（npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian run mcp-obsidian）を使うか、macOS では ~/Library/Logs/Claude/mcp-server-mcp-obsidian.log を tail します。