cyanheads/obsidian-mcp-server
Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP.
概要
obsidian‑mcp‑server は、AI エージェント（または MCP 互換クライアント）が Obsidian ボールトに保存されたノートを読み取り、編集できるようにするブリッジです。Obsidian Local REST API プラグインと通信し、シンプルな stdio インターフェースまたは軽量 HTTP サーバーを介して、一連の MCP ツール と リソース URL を公開します。サーバーは認証、フォルダー範囲の権限、および以下のような豊富な操作を処理します：
- ノートの取得（全文、単一の見出し、または解析されたドキュメントマップ）
- ノート、タグ、コマンドパレットエントリの一覧表示
- プレーンテキスト、JSONLogic、または BM25（Omnisearch プラグイン経由）によるノートの検索
- セクション、ブロック、フロントマターの作成、追加、パッチ、置換
- タグとフロントマターキーの管理
- ノートの削除（オプションでユーザー確認）と Obsidian UI でのノートのオープン。
すべての応答は JSON-RPC スタイルのオブジェクトで、詳細なエラーコードと回復ヒントが含まれており、自律エージェントが簡単に消費してアクションを実行できます。
主な機能
| 機能 | 説明 |
|---|---|
| MCP ベースの API | Model Context Protocol（MCP）を実装し、任意の MCP クライアント（Claude Desktop、Cursor、VS Code、カスタムボット）が stdio または HTTP 経由でツールを呼び出せるようにします。 |
| きめ細かい権限 | フォルダー範囲の読み取り/書き込みポリシー、読み取り専用モード、オプションの JWT/OAuth 認証でボールトを保護します。 |
| 豊富なノート操作 | ファイル全体の書き込み、単一の見出し、ブロック、フロントマターの置換、正規表現ベースの検索置換を実行します。 |
| タグとフロントマター管理 | タグ（フロントマター、インライン、またはその両方）の追加/削除/一覧表示、任意のフロントマターキーの取得/設定/削除。 |
| 検索の柔軟性 | テキスト検索、JSONLogic クエリ、または BM25 ランキングの Omnisearch（Omnisearch プラグインが存在する場合）。 |
| エージェント向け出力 | エラーには reason、JSON-RPC コード、recovery.hint が含まれます。変更ツールはサイズ差分と曖昧さデータを報告します。 |
| プラグ可能なストレージとロギング | インメモリ、ファイルシステム、Supabase、Cloudflare KV/R2/D1 バックエンド。構造化ロギング、オプションの OpenTelemetry トレーシング。 |
| 複数のデプロイオプション | Bun、Node（npx）、Docker、または Streamable HTTP サーバーとして実行。 |
典型的なユースケースの流れ
- セットアップ – Obsidian Local REST API プラグインをインストールし、API キーを生成し、
OBSIDIAN_API_KEY（オプションでOBSIDIAN_BASE_URL）を設定します。 - サーバーを起動 – HTTP エンドポイントには
bun run start:http、stdio にはbunx obsidian-mcp-server@latestを使用します。 - ツールを呼び出す – MCP 互換クライアントが JSON-RPC リクエストを送信します。例：
obsidian_get_noteでノートを取得、obsidian_append_to_noteで箇条書きを追加、obsidian_search_notesで関連コンテンツを検索。 - 応答を処理 – クライアントは構造化された結果を読み取り、エラーの
recovery.hintを確認し、フォローアップ呼び出し（例：obsidian_delete_noteで削除を確認）を行う場合があります。 - 反復 – エージェントはツールを連鎖させて、ボールト内の知識を自律的に構築、編集、整理できます。
インストールとクイックスタート
# クローンしてインストール（Bun 推奨）
git clone https://github.com/cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
bun install
# 環境テンプレートをコピーして API キーを追加
cp .env.example .env
# .env を編集 → OBSIDIAN_API_KEY=あなたのキー を設定
# stdio（Bun）または Docker で実行
bunx obsidian-mcp-server@latest # stdio
# または
docker run -i --rm -e OBSIDIAN_API_KEY=… ghcr.io/cyanheads/obsidian-mcp-server:latest
HTTP の場合：
MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=… bun run start:http
# サーバーは http://127.0.0.1:3010/mcp で稼働
誰がこれを使うべきか？
- AI エージェント – Obsidian に保存された個人知識ベースの読み書きが必要な場合。
- 自動化スクリプト – バルクノート更新、タグ整理、定期ノート生成用。
- 開発者ツール – 標準プロトコルを介して Obsidian ボールトを外部 IDE や CLI ユーティリティに公開したい場合。
- 研究パイプライン – Obsidian ボールトを構造化データストアとして扱い、プログラムによるアクセスが必要な場合。
制限と注意点
- Obsidian Local REST API プラグインに依存しています。これがないとサーバーは機能しません。
- 一部の操作（例：Windows CRLF ファイルでの見出し書き込み）は、古いプラグインバージョンで既知の問題があります。
- ノートの削除は API レベルで元に戻せません。回復できるのは Obsidian のローカルゴミ箱のみです。
- サーバーは独自の検索エンジンを提供しません – Omnisearch プラグインがインストールされている場合、そこに転送します。
- 権限はフォルダーレベルで適用されます。
OBSIDIAN_READ_PATHS/OBSIDIAN_WRITE_PATHSの設定ミスにより、アクセスが意図せずブロックされる可能性があります。
ライセンス
Apache 2.0 – 自由に使用、変更、配布できます。
関連
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト
- プロジェクト