obsidian-sync-mcp

Obsidian Sync MCP

MCP 経由で、あらゆる AI エージェントが Obsidian の保管庫にアクセスできるようにします。保管庫のファイルに対してローカルで実行するか、Self-hosted LiveSync と組み合わせてクラウドにデプロイすれば、マシンの電源が切れていても動作します。

例： スマートフォンから AI に「今日のデイリーノートには何が書かれている？」と尋ねると、Obsidian で開くためのリンクとともに、内容全体が返ってきます。

---

仕組み

サーバーは 2 つの方法で保管庫に接続します。

• ファイルシステムモード — 保管庫フォルダーから .md ファイルを直接読み取ります。データベースは不要です。
• CouchDB モード — ローカルまたはクラウドの CouchDB データベースから読み取ります。Self-hosted LiveSync（コミュニティ製 Obsidian プラグイン、ダウンロード数 60 万以上）を介して保管庫を CouchDB に同期します。MCP サーバーは、プラグインを支えるものと同じライブラリである livesync-commonlib を使用して CouchDB から直接読み取るため、チャンクを適切に処理し、E2E 暗号化をサポートします。

どちらのモードも、HTTP 経由で同じ MCP ツールを提供するため、Claude、Copilot、カスタムエージェントなど、Model Context Protocol に対応するあらゆるエージェントが接続できます。

---

セットアップを選択

常時利用可能にする必要がありますか？	LiveSync を使用していますか？	移動先
はい	はい	セットアップ A — 既存の CouchDB に MCP を追加
はい	いいえ	セットアップ B — CouchDB + MCP + LiveSync を一からセットアップ
いいえ	—	セットアップ C — ファイルシステムまたは CouchDB、npx または Docker

---

A. MCP をクラウドにデプロイ

常時稼働サーバー上に、LiveSync と CouchDB がすでにあります。あとはそのサーバーに MCP サーバーを追加でデプロイするだけです。

Fly.io セットアップスクリプトを使用（macOS/Linux、または Windows の WSL）：

git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh    # choose option 2 (MCP only)

スクリプトでは、CouchDB の接続情報、保管庫名、暗号化パスフレーズを入力します。

または、常時稼働サーバーで Docker イメージを実行：

docker run -p 8787:8787 \
  -v mcp-data:/data -e DATA_DIR=/data \
  -e COUCHDB_URL=https://your-couchdb:5984 \
  -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=yourpassword \
  -e COUCHDB_DATABASE=obsidian -e VAULT_NAME=MyVault \
  -e COUCHDB_PASSPHRASE=your-encryption-passphrase \
  -e COUCHDB_OBFUSCATE_PROPERTIES=false \
  -e MCP_AUTH_TOKEN=yourpassword \
  -e BASE_URL=https://your-server-url \
  ghcr.io/es617/obsidian-sync-mcp:latest

LiveSync で E2E 暗号化を使用している場合は、COUCHDB_PASSPHRASE を設定します。LiveSync の設定で「Obfuscate Properties」も有効にしている場合は、COUCHDB_OBFUSCATE_PROPERTIES=true を設定します。既存の保管庫では、サーバーは起動時にデータベースから実際の設定を検出し、不一致があれば警告を表示して修正します。値を LiveSync の設定と一致させる必要があるのは、新規の空のデータベースの場合のみです。LiveSync 1.0.33 以降とパスの難読化を使用して保管庫を作成した場合は、LiveSync のリカバリーコード（「Show current recovery code」から取得する sls-id-v1:...）を COUCHDB_ID_DERIVATION_KEY に設定してください。これにより、サーバーがノートのパスを解決できます。エージェントが HTTPS 経由で接続する際の OAuth コールバックに必要なため、BASE_URL には公開 URL を設定します。

MCP エンドポイントは https://your-app.fly.dev/mcp（Fly.io）または https://your-server:8787/mcp（HTTPS の背後で Docker を実行する場合）です。

Fly.io の料金については、費用を参照してください。

Fly.io を利用する場合は、flyctl が必要です。

curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc
fly auth login

---

B. すべてをクラウドにデプロイする

新規に始める場合、LiveSync はまだありません。CouchDB と MCP をまとめてデプロイし、その後 Obsidian で LiveSync を設定します。

Fly.io セットアップスクリプトを使用する場合（macOS/Linux、または Windows の WSL）：

git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
./deploy/setup.sh    # choose option 1 (CouchDB + MCP)

スクリプトは認証情報を生成し、データベースを作成して、デプロイします。表示された認証情報を保存してください。

または、常時稼働している任意のサーバーで Docker Compose を使用する場合：

git clone https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp

cat > .env <<EOF
COUCHDB_PASSWORD=changeme
MCP_AUTH_TOKEN=changeme-too
VAULT_NAME=MyVault
EOF

docker compose up -d

デプロイ後：

1. Obsidian で Self-hosted LiveSync をインストールし、セットアップの出力にある認証情報を使って設定します
2. MCP エンドポイントは https://your-app.fly.dev/mcp です（Fly.io の場合）。Docker Compose では、MCP ポートは localhost:8787 のみで公開されます。他のマシンからアクセスするには、前段に HTTPS トンネルまたはリバースプロキシを配置し（リモートアクセスを参照）、BASE_URL にその公開 URL を設定します
3. MCP_AUTH_TOKEN は、エージェントが接続するときに入力するパスワードです

Always-on server
├── CouchDB + persistent storage
└── MCP server
      ↑                    ↑
Obsidian + LiveSync    AI agents

Fly.io の手順には flyctl が必要です：

curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"  # add to ~/.zshrc or ~/.bashrc
fly auth login

---

費用（Fly.io）

セットアップ A とセットアップ B の両方に適用されます。

コンポーネント	費用
CouchDB + MCP VM（共有、512MB）	約 $3-4/月（LiveSync によって稼働状態が維持されます）
MCP 専用 VM（共有、256MB）	約 $0-2/月（アイドル時に一時停止します）
1GB 永続ボリューム	約 $0.15/月

2026 年 3 月時点で、Fly.io は月額 5 ドル未満の料金を免除する場合があり、共有 IPv4 を使用すれば実質無料になる可能性があります。いずれにしても、Obsidian Sync（月額 4 ドル）より安く、データの所有権も自分にあります。

---

C. マシン上で実行する

MCP サーバーをローカルで実行します。ファイルシステムモード（Vault ファイルを直接読み取る）と CouchDB モード（LiveSync を使用している場合）で動作します。エージェントがアクセスできるよう、マシンの電源を入れたままにする必要があります。

ファイルシステムモード（最も簡単）：

VAULT_PATH=~/Documents/MyVault \
VAULT_NAME=MyVault \
npx obsidian-sync-mcp

CouchDB モード（LiveSync を使用している場合）：

COUCHDB_URL=http://localhost:5984 \
COUCHDB_USER=admin \
COUCHDB_PASSWORD=yourpassword \
COUCHDB_DATABASE=obsidian \
COUCHDB_PASSPHRASE=your-encryption-passphrase \
COUCHDB_OBFUSCATE_PROPERTIES=false \
VAULT_NAME=MyVault \
npx obsidian-sync-mcp

LiveSync で E2E 暗号化を使用していない場合は、COUCHDB_PASSPHRASE を省略してください。LiveSync の設定でも「プロパティを難読化」を有効にしている場合は、COUCHDB_OBFUSCATE_PROPERTIES=true を設定してください。既存の Vault では、サーバーが起動時にデータベースから実際の設定を検出し、不一致があれば警告を出して修正します。値を LiveSync の設定と一致させる必要があるのは、新しい空のデータベースの場合のみです。Vault が LiveSync 1.0.33 以降とパスの難読化を使って作成されている場合は、サーバーがノートのパスを解決できるよう、LiveSync のリカバリーコード（sls-id-v1:...）を COUCHDB_ID_DERIVATION_KEY に設定してください。

または、Docker を使用する場合：

docker run -p 127.0.0.1:8787:8787 \
  -v mcp-data:/data -e DATA_DIR=/data \
  -e VAULT_PATH=/vault -v ~/Documents/MyVault:/vault \
  -e VAULT_NAME=MyVault \
  ghcr.io/es617/obsidian-sync-mcp:latest

MCP エンドポイントは http://localhost:8787/mcp です。

リモートアクセスが必要ですか？ トンネルを追加してください（マシンの電源を入れたままにする必要があります）：

cloudflared tunnel --url http://localhost:8787    # free
tailscale funnel 8787                             # or Tailscale
ngrok http 8787                                   # or ngrok

認証を使用する場合は、BASE_URL にトンネルの URL を設定してください。

---

ツール

ツール	説明
read_note	パスを指定してノートの Markdown コンテンツを読み取ります
write_note	ノートを作成または上書きします（コンテンツ全体を置き換えます）
edit_note	ノートを書き直さずに編集します — 追記、先頭への追加（フロントマターの後）、または完全一致するテキストの置換ができます
list_folders	ノートの件数とともに保管庫内のすべてのフォルダーを一覧表示します — フォルダー名の確認に使用します
list_tags	件数とともに保管庫内のすべてのタグを一覧表示します — 絞り込みの前にタグを確認する際に使用します
list_notes	タイムスタンプ付きでノートを一覧表示します。フォルダー、名前、タグ、日付で絞り込めます。名前または更新日時で並べ替えられます。
search_notes	ノート本文から語句を検索します（OR 検索、大文字と小文字を区別しない部分一致）。最初にパスとフロントマターのタイトルが検索されます。フォルダー、タグ、日付で絞り込めます。ステータス行にインデックスが追いついている CouchDB のシーケンスを示した後、各ノート本文は返さず、各パスと前後の文脈を 1 行ずつ返します。
delete_note	ノートを削除します
move_note	ノートを移動または名前変更します — フォルダー間で移動でき、移動先のフォルダーは自動的に作成されます
get_note_metadata	フロントマター、タグ、発信リンク、バックリンク、サイズ、タイムスタンプを取得します — ナレッジグラフの探索に使用します

すべてのツールの応答には、Mac および iOS で使える Obsidian ディープリンク（obsidian://open?vault=...&file=...）が含まれます。

「今日のノートに箇条書きを 1 つ追加して。」 「MCP サーバーに関するノートを探して、2 つ目のノートの誤字を修正して。」

---

認証

MCP_AUTH_TOKEN にパスワードを設定すると、認証が有効になります。

MCP_AUTH_TOKEN=mysecretpassword npx obsidian-sync-mcp

サーバーには、自己完結型の OAuth 2.1 プロバイダーが含まれています。エージェントが接続すると、次の処理が行われます。

1. パスワード入力ページが表示されたブラウザーウィンドウが開きます
2. MCP_AUTH_TOKEN のパスワードを入力します
3. エージェントがアクセストークンを取得し、透過的に更新します

セッションはすべての Claude インターフェース（デスクトップ、Web、モバイル）で共有され、サーバーを再起動しても維持されます。14 日間利用がないと、パスワードを再入力する必要があります（MCP_REFRESH_DAYS で設定可能です）。

OAuth 非対応のクライアント（curl、MCP Inspector、カスタムエージェント）では、Authorization: Bearer <MCP_AUTH_TOKEN> としてトークンを直接渡すこともできます。

MCP_AUTH_TOKEN が設定されていない場合、サーバーは認証なしで動作します — ローカルでの利用、またはプライベートネットワーク内での利用に適しています。

---

環境変数

変数	必須	デフォルト	説明
VAULT_PATH	ファイルシステムモード	—	Obsidian ボルトディレクトリへのパス
COUCHDB_URL	CouchDB モード	—	CouchDB サーバーの URL
COUCHDB_USER	CouchDB モード	admin	CouchDB のユーザー名
COUCHDB_PASSWORD	CouchDB モード	—	CouchDB のパスワード（必須）
COUCHDB_DATABASE	CouchDB モード	obsidian	CouchDB のデータベース名。サーバーが作成することはありません。存在しない場合、起動時にエラーで失敗します
COUCHDB_PASSPHRASE	CouchDB モード	—	LiveSync の E2E 暗号化パスフレーズ（プラグインの設定と一致する必要があります）
COUCHDB_OBFUSCATE_PROPERTIES	CouchDB モード	false	LiveSync で「Obfuscate Properties」が有効な場合は true に設定します（データベース内のファイルパス、サイズ、日付を難読化します）。既存のボルトでは、実際の設定が起動時に自動検出されます。この値は、新規の空のデータベースで使用する形式のみを決定します
COUCHDB_ID_DERIVATION_KEY	CouchDB モード	—	LiveSync の「independent ID derivation」復旧コード（sls-id-v1:...）。パス難読化を使用する LiveSync 1.0.33 以降で作成されたボルトのノートを読み書きする場合に必要です。古い（パスフレーズ由来の）ボルトでは未設定のままにします。LiveSync の「Show current recovery code」から取得してください
COUCHDB_CASE_SENSITIVE	CouchDB モード	false	LiveSync のボルトで「Handle filenames as case-sensitive」が有効な場合に限り、true に設定します。ボルトの設定と一致する必要があります。一致しない場合、難読化されたドキュメント ID を解決できず、明確なメッセージとともにサーバーの起動に失敗します。それ以外の場合は未設定のままにします
VAULT_NAME	両方	MyVault	ボルト名（ディープリンクとインデックスの保存に使用）
MCP_AUTH_TOKEN	任意	—	認証用のパスワード
BASE_URL	任意	http://localhost:PORT	公開 URL（トンネル使用時の OAuth コールバック用）
PORT	任意	8787	HTTP ポート
HOST	任意	0.0.0.0	バインドアドレス（localhost のみに制限する場合は 127.0.0.1）
MCP_ALLOWED_HOSTS	任意	—	認証なしモードで受け入れる追加の Host 値をカンマ区切りで指定します（例：192.168.1.5,mybox.local）。認証なしモードでは、ブラウザーの DNS リバインディングを防ぐため、これ以外の Host は拒否されます。localhost は常に許可されます。MCP_AUTH_TOKEN が設定されている場合は無視されます。
DATA_DIR	任意	~/.obsidian-mcp	永続データ（メタデータインデックス、認証トークン）の保存先ディレクトリ
LOG_LEVEL	任意	—	詳細なログ（ライブラリログ、変更フィード、インデックス同期）を有効にするには debug に設定します
DISPLAY_TIMEZONE	任意	サーバーのタイムゾーン	search_notes のステータス行に表示されるサーバー時刻の人間向け表記に使用する IANA タイムゾーン（UTC も常に併記されます）。例：Europe/Berlin。無効なタイムゾーンの場合は、起動時の警告とともに UTC にフォールバックします
MCP_REFRESH_DAYS	任意	14	認証セッションの有効期限までの日数
READ_ONLY	任意	false	すべての書き込みツール（write_note、edit_note、delete_note、move_note）を無効にするには true に設定します。読み取りツールのみが MCP 経由で公開され、ボルトのバックエンドも書き込みを拒否します。複数の AI クライアントとサーバーを共有し、書き込みアクセスを明示的な許可制にしたい場合に便利です。これは MCP クライアントからボルトを保護するものであり、データベースレベルでの保証ではありません。CouchDB 自体に書き込みを拒否させるには、サーバーの CouchDB ユーザーからの書き込みを拒否する validate_doc_update 関数など、CouchDB 側の制御を使用してください。
WRITE_FOLDERS	任意	—	書き込みを許可する、ボルトからの相対パスで指定したフォルダーをカンマ区切りで指定します（例：MCP,Inbox）。設定すると、ボルト全体を読み取り可能な状態に保ちながら、これらのフォルダー外のパスへの write_note、edit_note、delete_note、move_note を拒否します（move_note では、移動元と移動先の両方に書き込みが許可されている必要があります）。MCP_INSTRUCTIONS とは異なり、サーバー側で強制されます。大文字と小文字を区別し、フォルダー境界を考慮して照合します（MCP は MCP/note.md には一致しますが、MCP-private/note.md には一致しません）。READ_ONLY=true の場合は無視されます。未設定の場合、ボルト全体への書き込みが可能です。
MCP_INSTRUCTIONS	任意	—	サーバーの MCP instructions（クライアントがシステムプロンプトに挿入する文字列）に追加するテキストです。フォルダー構成、命名規則、避けるべきフォルダーなど、ボルト固有の規約をサーバーに組み込み、クライアントごとの設定なしですべての MCP クライアントに適用するために使用します。ベストエフォートです。すべてのクライアントが instructions を尊重するとは限りません。
MCP_INSTRUCTIONS_FILE	任意	—	内容を MCP の instructions に追加するファイル（例：Markdown）へのパスです。複数行の規約を指定する場合は、MCP_INSTRUCTIONS より簡単です。両方が設定されている場合はファイルが優先され、MCP_INSTRUCTIONS は無視されます（起動時に警告が表示されます）。ファイルが存在しない、読み取れない、または 32 KB を超える場合、起動時に致命的なエラーが発生します。このファイルは、サービスユーザーだけが書き込める場所（例：chmod 600）に保存してください。内容はすべての MCP セッションのシステムプロンプトに挿入されるため、このファイルへの書き込み権限は、すべてのクライアントへのプロンプトインジェクション権限を意味します。
ファイルシステムモードでは VAULT_PATH、CouchDB モードでは COUCHDB_URL を設定します。

---

エージェントなしで試す

MCP Inspector を使って、サーバーを対話的にテストします。

VAULT_PATH=~/Documents/MyVault npx obsidian-sync-mcp &
npx @modelcontextprotocol/inspector

トランスポートを Streamable HTTP に設定し、http://localhost:8787/mcp を入力して接続します。

---

更新方法

実行方法	更新方法
npx obsidian-sync-mcp	自動 — npx が最新バージョンを取得します
Fly.io	セットアップを実行したのと同じディレクトリから fly deploy を実行します。fly.toml を紛失した場合は、fly config save --app your-app-name を実行して復元します。
Docker	docker pull ghcr.io/es617/obsidian-sync-mcp:latest を実行して再起動します。イメージは非特権ユーザーの node（uid 1000）として実行されます。データボリュームが root として実行される古いイメージによって作成されている場合は、書き込み可能にするため、一度 docker run --rm -v mcp-data:/data alpine chown -R 1000:1000 /data を実行します（バインドマウントの場合は、ホスト側のディレクトリに対して chown -R 1000:1000 を実行します）。

---

既知の制限事項

• インスタンスごとに単一の Vault。 各サーバーは 1 つの Vault に接続します。複数の Vault を使う場合は、異なるポートで複数のインスタンスを実行してください。
• Fly.io では単一のマシンのみ。 認証状態はメモリ内に保持されるため、複数のマシンを使うと OAuth フローが機能しません。セットアップスクリプトがこれを自動的に適用します。
• 競合解決機能はありません。 エージェントと Obsidian が同じノートを同時に編集した場合、後から行われた書き込みが優先されます。
• テキストのみ。 バイナリ添付ファイルは MCP ツールから公開されません。
• ディープリンクの動作はクライアントによって異なります。 Obsidian の obsidian:// ディープリンクは、すべてのツールの応答に含まれます。Claude Mobile とブラウザーでは機能しますが、一部のクライアント（Claude Desktop など）ではクリック可能なリンクとして表示されない場合があります。
• Node 22+ が必要です。
• セットアップスクリプトには bash が必要です。 deploy/setup.sh スクリプトは macOS と Linux で動作します。Windows では WSL または Git Bash を使用してください。

---

安全性

このサーバーは、AI エージェントに Obsidian Vault への読み取り／書き込みアクセスを許可します。

エージェントはノートを変更および削除できます。 バックアップを保管してください。ツールの承認は慎重に行ってください。

認証は任意です。 インターネットに公開する場合は、必ず MCP_AUTH_TOKEN を設定してください。

本番環境では HTTPS を使用してください。 トンネルを使用するか、リバースプロキシの背後にデプロイしてください。

本番環境で LOG_LEVEL=debug のままにしないでください。 デバッグログには、ノートの内容を含む各ツール呼び出しの引数と、エラーのスタック全体が記録されます。COUCHDB_URL に含まれる認証情報は、すべてのログレベルでログからマスキングされます。

このソフトウェアは、MIT ライセンスのもとで現状有姿で提供されます。エージェントが Vault で行うことについては、利用者が責任を負います。

---

開発

git clone --recursive https://github.com/es617/obsidian-sync-mcp.git
cd obsidian-sync-mcp
npm install && npm run build
npm test          # unit tests
npm run test:e2e  # integration tests

---

ライセンス

MIT — LICENSE を参照してください。

謝辞

• vrtmrz による Self-hosted LiveSync — Obsidian プラグインと CouchDB 同期プロトコル
• vrtmrz による livesync-commonlib — LiveSync ドキュメント形式の読み書きに使われる共有ライブラリ
• FastMCP — TypeScript MCP フレームワーク
• CouchDB — ドキュメントデータベース
• Fly.io — デプロイプラットフォーム