Obsidian MCP Server

obsidian-mcp-server

Obsidian の保管庫向け Go 製 Model Context Protocol（MCP）サーバーです。AI エージェントや開発ツールが、Obsidian のインスタンスを起動せずに保管庫へ直接ファイルシステムからアクセスできます。

機能

• ノートとディレクトリの読み取り、書き込み、一覧表示 — MCP ツール経由で操作できます
• フロントマター — YAML フロントマターを解析し、形式を保持したまま更新します
• タグ — インラインの #tags を抽出し、保管庫全体のタグ数を集計して、タグを追加・削除します
• バックリンク — 必要に応じて逆リンクグラフを作成します（ウィキリンクと Markdown リンク）
• 変更操作 — 見出しを基準にしたパッチ、安全な削除、確認ガード付きの移動に対応します
• 全文検索 — BM25 Okapi によるランキング検索と一致箇所のスニペット表示に対応します
• 正規表現／glob 検索 — RE2 正規表現またはファイルパスの glob を使って、パスとコンテンツを検索します
• パスのセキュリティ — 4 層の検証に対応します：字句チェック、無視対象／拡張子フィルター、大文字と小文字を区別しない存在確認、シンボリックリンクによる範囲外アクセスの防止
• Stdio トランスポート — あらゆる MCP クライアント（Claude Code、Claude Desktop など）で動作します
• Streamable HTTP トランスポート（オプション）— TLS 1.3 とベアラートークン認証がデフォルトで有効です。明示的に範囲を広げない限り、ループバック接続のみに制限されます。設定の --transport http と SECURITY.md § HTTP トランスポートを参照してください
• Obsidian への依存なし — 保管庫ディレクトリを直接操作します
• トークン数のカウント — レスポンスにおおよそのトークン数が含まれます（cl100k_base）

MCP ツール

ツール	説明	パラメーター
read_note	ノートの内容とメタデータを読み取ります	path（必須）、prettyPrint — レスポンスにはetagが含まれます
write_note	ノートを作成または更新します	path、content（必須）、mode：overwrite/append/prepend、if_match（任意のetag）
list_directory	ファイルとサブディレクトリを一覧表示します	path（空の場合は保管庫のルート）、prettyPrint
get_frontmatter	ノートのYAMLフロントマターを読み取ります	path（必須）、prettyPrint
update_frontmatter	フロントマターのキーを設定または削除します（書式を保持）	path（必須）、updates（JSONオブジェクト）、removeKeys（JSON配列）、if_match（任意のetag）
manage_tags	ノートのタグを追加または削除します	path、action：add/remove（必須）、tag（必須）、location：frontmatter/inline、if_match（任意のetag）
list_all_tags	保管庫全体のタグを集計し、件数とともに表示します	prettyPrint
get_backlinks	対象のノートにリンクしているノートをすべて検索します	path（必須）、prettyPrint
patch_note	見出しを基準にノートへパッチを適用します	path、heading、position：before/after/replace_body、content（すべて必須）、if_match（任意のetag）
delete_note	ノートを.obsidian-mcp/trashに移動します（確認が必要）。代わりに完全削除するにはpermanent: trueを指定します	path、confirm（pathと完全一致する必要があります）、permanent（任意、デフォルトはfalse）、if_match（任意のetag）
move_note	保管庫内でノートを移動または名前変更します（確認が必要）。デフォルトでは、曖昧さのない被リンクを書き換えます	src、dst、confirm（srcと完全一致する必要があります）、updateLinks（bool、デフォルトはtrue）、dryRun（bool、デフォルトはfalse）、if_match（任意のetag。dryRunがtrueの場合は無視されます）
search_notes	BM25による全文検索を行い、ランキング結果と一致箇所のスニペットを返します	query（必須）、limit、maxMatchesPerFile、caseSensitive、searchContent、searchFrontmatter、pathScope、prettyPrint
search_regex	RE2正規表現またはglobパターンを使用して検索します	pattern（必須）、isGlob、scope、limit、maxMatchesPerFile、prettyPrint
read_multiple_notes	1回のリクエストで複数のノートの内容を読み取ります	paths（必須、JSON配列）、summary（bool、デフォルトはfalse）、headChars（int、デフォルトは200）— 各エントリにはetagが含まれます
get_notes_info	ノートの全文を読み取らずに、複数のノートのメタデータを取得します	paths（必須、JSON配列）— 各エントリにはetagが含まれます
get_vault_stats	保管庫全体の統計情報を集計して取得します	includeTokenCounts（bool、デフォルトはfalse）
get_periodic_note	定期ノート（日次、週次、月次、四半期ごと、または年次）を取得します	granularity（必須、enum：daily/weekly/monthly/quarterly/yearly）、offset（int、デフォルトは0）、createIfMissing（bool、デフォルトはfalse）
get_recent_periodic_notes	直近の定期ノートをN件取得します	granularity（必須、enum：daily/weekly/monthly/quarterly/yearly）、count（int、デフォルトは5）、summary（bool、デフォルトはtrue）
get_recent_changes	保管庫内で最近変更されたノートを一覧表示します	limit（int、デフォルトは10）、since（string、ISO-8601）、summary（bool、デフォルトはtrue）
audit_notes	孤立ノート、リンク切れ、タグのないノート、タイトルの重複など、保管庫の整理状態を監査します	classes（JSON配列：orphans/dangling-links/untagged/duplicate-titles、デフォルトはすべて）、limit（クラスごとのint、デフォルトは20）
get_note_outline	ノートの本文を除き、見出しの階層（レベル、テキスト、行番号）を返します	path（必須）、prettyPrint
read_note_lines	ノートの指定範囲の行を読み取ります	path、startLine（必須）、lineCount（int、デフォルトは200、上限は2000）
rename_tag	フロントマターとインラインの出現箇所を含め、保管庫全体でタグ名を変更します	oldTag、newTag（両方とも必須）
replace_in_note	1つのノート内で、リテラルまたは正規表現による範囲指定の検索と置換を行います	path、pattern、replacement（すべて必須）、isRegex（bool、デフォルトはfalse）、maxOccurrences（int、デフォルトは0＝無制限）
search_notes、search_regex、list_directory、get_recent_changes の結果には、--vault-name をもとに作成された、ノートごとの obsidian://open deepLink フィールドも含まれます（「Configuration」を参照）。

Notes

patch_note の動作：position は、見出しに対して content を挿入する位置を指定します。

• before — 見出し行の直前に挿入します
• after — 見出し本文の後（次の同じレベルまたは上位レベルの見出しの前）に挿入します
• replace_body — 見出し行から次の同じレベルの見出しまでの内容をすべて置き換えます

search_notes のパラメーター：

Parameter	Type	Default	Description
query	string	required	検索クエリです。複数語のクエリでは OR ロジックが使われ、フレーズ全体にはボーナススコアが加算されます。
limit	integer	20	結果の最大数
maxMatchesPerFile	integer	3	結果ごとの一致スニペットの最大数
caseSensitive	boolean	false	大文字と小文字を区別して照合します
searchContent	boolean	true	スコアリングにノート本文を含めます
searchFrontmatter	boolean	true	スコアリングにフロントマターの値を含めます
pathScope	string	—	検索範囲を制限するグロブパターン（例：Daily Notes/*）
prettyPrint	boolean	false	JSON をインデント付きで整形します

返り値：{ query, results: [{ path, score, matchCount, matches: [{line, snippet, term}], tokenCount, reason }], total }

search_regex のパラメーター：

Parameter	Type	Default	Description
pattern	string	required	RE2 正規表現またはグロブパターン
isGlob	boolean	false	パターンをファイルパスのグロブとして扱います（** はディレクトリをまたいで一致します）
scope	string	content	path、content、または both
limit	integer	20	結果の最大数
maxMatchesPerFile	integer	5	結果ごとの一致スニペットの最大数
prettyPrint	boolean	false	JSON をインデント付きで整形します

返り値：{ pattern, scope, results: [{ path, matches: [{line, snippet}] }], total }

バッチツール（read_multiple_notes、get_notes_info）：paths パラメーターは JSON 配列文字列です。例：'["Notes/foo.md","Notes/bar.md"]'。summary:true を指定すると、全コンテンツの代わりに headOf（headChars で指定した先頭 N 文字、デフォルトは 200）が返されます。これは、大きなノートがコンテキストの制限を超えないようにするのに便利です。どちらのツールも --max-batch（デフォルトは 10）を適用します。パスが上限を超えるリクエストは、通知なしで切り詰められ、レスポンスには "truncated": true が含まれます。

楽観的同時実行制御（if_match / etag）：read_note、read_multiple_notes、get_notes_info は、ノートのコンテンツの SHA-256 etag を返します。この値を write_note、patch_note、update_frontmatter、manage_tags、delete_note、move_note の if_match に渡すと、条件付きで書き込みが行われます。読み取り後にノートが変更されている場合、他のユーザーの編集を黙って上書きする代わりに、呼び出しは REVISION_CONFLICT エラーで失敗します。if_match はどこでも省略可能です。省略した場合は、従来どおり無条件で書き込みます。注意点が2つあります。まだ存在しないノートに if_match を指定すると、常に競合となり、ノートは作成されません。また、move_note の dryRun:true によるプレビューでは if_match は適用されません。

定期ノート（get_periodic_note、get_recent_periodic_notes）：フォルダーと粒度ごとの日付形式の設定は、Vault 内の .obsidian/plugins/periodic-notes/data.json から読み込まれます。このファイルがない場合は、組み込みのデフォルトが使われます。日次ノートでは Daily Notes/ に YYYY-MM-DD、週次ノートでは Weekly Notes/ に gggg-[W]ww が使われ、それ以降も同様です。offset=0 は現在の期間、offset=-1 は前の期間（昨日、先週など）、offset=+1 は次の期間に解決されます。createIfMissing=true を指定すると、解決されたパスにノートが存在しない場合、空のノートが作成されます。 get_vault_stats：noteCount、totalBytes、totalLinks、totalTags、topTags（件数順の上位20件）、oldestNote、newestNote、vaultRootを返します。includeTokenCounts:trueを設定すると、すべてのノートでトークン数をカウントします。大規模なVaultでは処理コストが高いため、デフォルトでは無効になっています。

audit_notes の分類：

• orphans — タグがなく、流入するウィキリンクやMarkdownリンクもないノート（完全に孤立したノート）
• dangling-links — 存在しないVault内のパスへのリンクを含むノート（リンク切れの参照）
• untagged — フロントマターのタグもインラインの#tagsもないノート
• duplicate-titles — 同じファイル名の語幹を持つ複数のノート。ウィキリンクが曖昧になる原因です

各分類の結果はlimit件（デフォルトは20件）までに制限されます。結果が省略された場合、レスポンスには"truncated": trueが含まれます。

MCP プロンプト

プロンプトはサーバーで定義された会話の開始文で、ホスト（Claude Code、Claude Desktop）がUIに表示します。各プロンプトはVaultの最新データを取得し、LLMですぐに使えるメッセージを作成します。

プロンプト	説明	引数
summarize_note	ノートを要約します：重要なポイント3つ、エンティティ、未解決の質問	path（必須）
daily_note_review	デイリーノートを確認します：持ち越しのTODO、リンクの提案、不足しているタグ	offset（整数、デフォルトは0）
weekly_review	過去7日分のデイリーノートから週次の振り返りを作成します	weekOffset（整数、デフォルトは0）
find_related	リンクする価値のある関連ノートを関係の種類ごとにまとめて提案します	path（必須）
vault_health_check	孤立ノート、リンク切れ、タグなしノート、タイトル重複を監査し、修正の優先順位を付けます	(なし)

プロンプトはホストのプロンプト選択メニュー（Claude Codeの/など）から実行します。Vaultを変更することはありません。

MCP リソース

リソースは読み取り専用のVaultデータで、明示的なツール呼び出しなしでホストが会話のコンテキストウィンドウに直接添付できます。

リソース／テンプレート	URI	MIME	説明
Vault統計情報	obsidian://vault/stats	application/json	ノート数、合計サイズ、上位10件のタグ、Vaultのルート
タグインデックス	obsidian://vault/tags	application/json	件数順のすべてのタグとノート数
ノートの内容	obsidian://note/{path}	text/markdown	任意のVault内ノートの生のMarkdown（フロントマター＋本文）
定期ノート	obsidian://periodic/{granularity}	text/markdown	現在のデイリー／ウィークリー／マンスリー／クォータリー／年次ノート
バックリンク	obsidian://backlinks/{path}	application/json	行番号と抜粋を含む、対象にリンクしているすべてのノート

静的リソース（obsidian://vault/*）は、リソース選択メニューで常に利用できます。テンプレートリソースはホストが読み取る際に解決されます。ノートが存在しない場合、エラーではなく説明を含む空の本文を返します。

インストール

インストールスクリプト

お使いのOS／アーキテクチャに合ったバイナリをダウンロードし、チェックサムを検証して、 ~/.local/binにインストールします（2つ目の引数でインストール先を変更できます）。

curl -fsSL https://raw.githubusercontent.com/tylern91/obsidian-mcp-server/main/install.sh | sh

latestの代わりにバージョンを固定します：

curl -fsSL https://raw.githubusercontent.com/tylern91/obsidian-mcp-server/main/install.sh | sh -s -- v0.2.0

Claude Desktop（.mcpbバンドル）

最新リリースからobsidian-mcp-<version>.mcpbをダウンロードしてダブルクリックすると、Claude Desktopが拡張機能をインストールし、Vaultのパスを尋ねます。JSONを手動で編集する必要はありません。

リリースバイナリ

最新リリースからビルド済みバイナリをダウンロードし、チェックサムを検証してインストールします：

# macOS (Apple Silicon) — swap the asset name for your platform (darwin-amd64, linux-amd64, linux-arm64)
curl -fLO https://github.com/tylern91/obsidian-mcp-server/releases/latest/download/obsidian-mcp-<version>-darwin-arm64.tar.gz
curl -fLO https://github.com/tylern91/obsidian-mcp-server/releases/latest/download/obsidian-mcp-<version>-darwin-arm64.tar.gz.sha256
shasum -a 256 -c obsidian-mcp-<version>-darwin-arm64.tar.gz.sha256
tar -xf obsidian-mcp-<version>-darwin-arm64.tar.gz
install -m 0755 obsidian-mcp-<version>-darwin-arm64/obsidian-mcp ~/.local/bin/obsidian-mcp

Homebrew（macOS/Linux）

brew tap tylern91/obsidian-mcp
brew install obsidian-mcp

go install

ソースからビルドするにはGo 1.27以降が必要です。古いGoでGOTOOLCHAIN=localを指定してビルドする場合は、先にアップグレードする必要があります。GOTOOLCHAIN=auto（Go 1.21以降のデフォルト）を指定すると、対応するツールチェーンが自動的にダウンロードされます。

go install github.com/tylern91/obsidian-mcp-server/cmd/obsidian-mcp@latest

ソースからビルドする

Go 1.27 以降が必要です。古い Go で GOTOOLCHAIN=local を指定してビルドするには、先にアップグレードする必要があります。Go 1.21 以降のデフォルトである GOTOOLCHAIN=auto は、一致するツールチェーンを自動的にダウンロードします。

git clone https://github.com/tylern91/obsidian-mcp-server.git
cd obsidian-mcp-server
make build

使い方

Claude Code

claude mcp add obsidian -s user \
  -e OBSIDIAN_VAULT_PATH="/path/to/your/vault" \
  -- obsidian-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

Cursor

インストール後にボルトのパスを編集してください。ディープリンクでは事前にパスを把握できません。

VS Code

インストール後にボルトのパスを編集してください。ディープリンクでは事前にパスを把握できません。

直接実行

obsidian-mcp --vault /path/to/your/vault

バージョンを表示して終了します。

obsidian-mcp --version

設定

設定の優先順位は CLI フラグ > 環境変数 > デフォルト値 です。

フラグ	環境変数	デフォルト	有効な値
--vault	OBSIDIAN_VAULT_PATH	(必須)	既存のディレクトリへの絶対パスまたは相対パスです。起動時に検証され、存在しないパスやファイル（ディレクトリではないもの）が指定されると、ただちにエラーになります。前後の空白は削除されます。
--version	—	—	バイナリのバージョンを標準出力に表示して終了します。--vault は不要です。
--extensions	OBSIDIAN_EXTENSIONS	.md,.markdown,.txt,.canvas	カンマ区切りのリストです。各項目は . で始まる必要があります（例：.md）。項目の前後の空白は削除され、空の項目は破棄されます。これらの拡張子のいずれかに一致するファイルのみが MCP ツールから参照できます。
--ignore	OBSIDIAN_IGNORE	.obsidian,.git,node_modules,.DS_Store,.trash	トラバーサル時にスキップするファイル名／ディレクトリ名のカンマ区切りリストです。名前で照合し、glob は使いません。前後の空白は削除され、空の項目は破棄されます。
--pretty	OBSIDIAN_PRETTY	false	CLI では、値を付けずに --pretty を指定すると有効になります。環境変数では、Go の strconv.ParseBool が受け付ける値（1、t、T、true、TRUE、True、0、f、F、false、FALSE、False）を指定できます。それ以外の値を指定すると、起動時にエラーになります。
--max-batch	OBSIDIAN_MAX_BATCH	10	1 以上の整数です。整数以外の値または 1 未満の値を指定すると、起動時にエラーになります。1 回のバッチツール呼び出しで処理するファイル数の上限です（フェーズ 4）。値を大きくすると、メモリ使用量と応答あたりのトークン数が増加します。バッチが非常に大きいと、AI クライアントのコンテキストウィンドウを超過したり、個々のツール呼び出しが遅くなったりすることがあります。ボルト内のファイルが小さい場合を除き、デフォルト値かその近くに設定してください。
--max-results	OBSIDIAN_MAX_RESULTS	20	1 以上の整数です。整数以外の値または 1 未満の値を指定すると、起動時にエラーになります。返される検索結果数の上限です。値を大きくすると、応答のトークン数が増加します。検索ごとに数百件の結果を返すと、関連性の低い項目によって AI クライアントのコンテキストウィンドウを使い果たすことがあります。より広い結果セットが必要となる精度と再現率のトレードオフがある場合にのみ、値を増やしてください。
--log-level	OBSIDIAN_LOG_LEVEL	warn	debug、info、warn、error のいずれかです（小文字、大文字と小文字を区別）。不明な値はエラーにも警告ログにもならず、warn にフォールバックします。
--read-only	OBSIDIAN_READ_ONLY	false	CLI では、値を付けずに --read-only を指定すると有効になります。環境変数では、--pretty と同じ ParseBool の規則が適用されます。有効にすると、変更を伴うツール（write_note、delete_note、move_note など）は登録されず、tools/list に表示されません。
--trash-retention-days	OBSIDIAN_TRASH_RETENTION_DAYS	30	0 以上の整数です。整数以外の値または負の値を指定すると、起動時にエラーになります。デフォルトでは、delete_note はノートを完全に削除せず、.obsidian-mcp/trash/<timestamp>/<path> に移動します。この日数より古いエントリは、起動時に 1 回削除されます。
--vault-name	OBSIDIAN_VAULT_NAME	ボルトディレクトリのベース名	search_notes、search_regex、list_directory、get_recent_changes の結果に含まれる obsidian://open?vault=<name>&file=<path> ディープリンクの生成に使用します。ボルトディレクトリの名前が Obsidian 上の表示名と一致しない場合は、明示的に設定してください。
--transport	OBSIDIAN_TRANSPORT	stdio	stdio または http です。http を指定すると、stdio 経由で MCP を通信する代わりに、TLS で保護された Streamable HTTP リスナーを起動します。SECURITY.md § HTTP transport を参照してください。
--http-bind	OBSIDIAN_HTTP_BIND	127.0.0.1	--transport http のバインドアドレスです。--allow-non-loopback も設定されていない限り、ループバック以外のアドレスは拒否されます。
--http-port	OBSIDIAN_HTTP_PORT	8443	--transport http のポートです。
--allow-non-loopback	OBSIDIAN_ALLOW_NON_LOOPBACK	false	--http-bind にループバック以外のアドレスを指定できるようにします。空でない --allowed-hosts と --allowed-origins が必要です。明示的に 3 つのフラグすべてを指定する必要があります。
--allowed-hosts	OBSIDIAN_ALLOWED_HOSTS	(空)	--transport http の Host ヘッダー許可リストです。カンマ区切りで指定します。--allow-non-loopback と併せて指定する必要があります。
--allowed-origins	OBSIDIAN_ALLOWED_ORIGINS	(空)	--transport http の Origin ヘッダー許可リストです。カンマ区切りで指定します。--allow-non-loopback と併せて指定する必要があります。
--client-ca	OBSIDIAN_CLIENT_CA	(なし)	信頼するクライアント CA を記載した PEM ファイルへのパスです。--transport http の相互 TLS を必須にします。有効なクライアント証明書がない接続は拒否されます。

使用例

# Override extensions to include Excalidraw drawings
obsidian-mcp --vault ./my-vault --extensions ".md,.canvas,.excalidraw"

# Add a custom ignore pattern alongside defaults (you must repeat the defaults
# you want to keep — values fully replace, not merge)
obsidian-mcp --vault ./my-vault \
  --ignore ".obsidian,.git,node_modules,.DS_Store,.trash,Archive,Templates"

# Enable pretty JSON via env var (any ParseBool-compatible truthy value works)
OBSIDIAN_PRETTY=1 obsidian-mcp --vault ./my-vault
OBSIDIAN_PRETTY=true obsidian-mcp --vault ./my-vault

# Verbose logging while debugging an integration
OBSIDIAN_LOG_LEVEL=debug obsidian-mcp --vault ./my-vault

# Streamable HTTP transport instead of stdio (loopback only, TLS + bearer
# token auto-generated on first run — see SECURITY.md § HTTP transport)
obsidian-mcp --vault ./my-vault --transport http --http-port 8443

優先順位の動作：OBSIDIAN_LOG_LEVEL=debug をエクスポートした状態で obsidian-mcp --vault ... --log-level info を実行すると、info で動作します。明示的に指定したフラグが優先されます。未設定のフラグは環境変数を引き継ぎ、どちらも設定されていない場合はデフォルトが適用されます。

セキュリティ

ファイルシステム上の操作を行う前に、すべてのパスが4層のセキュリティモデルによって検証されます。

1. 字句解析 — 絶対パス、.. によるパストラバーサル、ヌルバイトを拒否します
2. フィルター — 無視対象のパターン（.git、.obsidian など）と未承認の拡張子をブロックします
3. 存在確認 — 大文字と小文字を区別しないフォールバックを用いてファイルの存在を確認し、曖昧な一致を拒否します
4. シンボリックリンク — シンボリックリンクを解決し、リンク先がVaultのルート内にあることを確認します

オプションの --transport http リスナーには、独自のセキュリティ対策（TLS、ベアラー認証、デフォルトでループバックのみ、セッションバインディング）があります。詳細については、SECURITY.md § HTTP transport を参照してください。

プロジェクト構成

cmd/obsidian-mcp/     Entry point, transport selection (stdio/http)
internal/
  config/             CLI flags, env vars, defaults
  vault/              Path security, CRUD, frontmatter, tags, links, mutations
  tools/              MCP tool registrations and handlers
  response/           Token counting, JSON formatting
  search/             BM25 ranked search, regex/glob
  periodic/           Periodic note resolution (Phase 4)
  prompts/            MCP Prompt templates
  resources/          MCP Resource registrations
  httptransport/      Streamable HTTP transport: TLS, bearer auth, session binding
testdata/vault/       Fixture vault for tests

開発

make build    # compile binary
make test     # go test -race ./...
make vet      # go vet ./...
make fmt      # gofmt + goimports
make run ARGS="--vault /path/to/vault"
make help     # list all targets

ライセンス

Apache-2.0