Skip to main content
Glama
asann3

obsidian-vault-mcp

by asann3
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

obsidian-vault-mcp

ディスク上の Obsidian Vault を直接読み書きする MCP サーバー。Obsidian アプリを起動しておく必要はない。 読み書き・検索に加えて、[[wikilink]] のグラフ探索（バックリンク、N-hop 近傍、未解決リンク、孤立ノート）を提供する。

  • TypeScript / 公式 MCP SDK v2（仕様 2026-07-28 と 2025 系の両方に対応）

  • Streamable HTTP（Bearer トークン）と stdio

  • Node.js 24+ で node src/main.ts として直接実行できる。Claude Desktop 用には依存を同梱した .mcpb（デスクトップ拡張）も作れる

使い方

Claude Desktop（デスクトップ拡張 / ネットワークに何も公開しない）

pnpm install && pnpm pack:mcpb     # obsidian-vault-mcp.mcpb ができる

生成された .mcpb を Claude Desktop の Settings > Extensions にドラッグして、インストールする。設定画面で Vault のフォルダを選ぶ。 初期値は読み取り専用なので、書き込ませたいときは「Read-only」をオフにする（「Writable folders」で書き込めるフォルダも限定できる）。

Claude Code（ローカル、stdio）

claude mcp add --scope user obsidian --env OBSIDIAN_VAULT_PATH=$HOME/vault --env OBSIDIAN_MCP_READONLY=1 -- node /path/to/obsidian-vault-mcp/src/main.ts --stdio

Claude Code（リモートのサーバーへ HTTP で接続）

下の「サーバーへのデプロイ」を参照。

Related MCP server: Obsidian MCP Server

構成（サーバーに常駐させる場合）

[各端末の Obsidian] ⇄ CouchDB
                          ⇅  livesync-cli daemon（E2EE v2・パス難読化に対応）
                     /srv/vault（平文のミラー）
                          ↑ 読み書き
                     obsidian-vault-mcp  127.0.0.1:8787
                          ↑ HTTPS のリバースプロキシ（tailscale serve、Caddy など）
                   Claude Code / その他 MCP クライアント

MCP での書き込みは livesync-cli がファイル監視で拾い、CouchDB 経由で各端末に配信する。

ツール

種別

ツール

内容

読み取り

list_notes

フォルダ内のノートを更新日時の新しい順に一覧

read_note

本文を読む。見出しセクションだけ読む、ページングも可。編集用の hash を返す

get_note_info

frontmatter・タグ・エイリアス・見出し構成・リンク数

search_notes

全文検索（AND、大文字小文字区別なし、日本語可）または正規表現。フォルダ・タグで絞り込み

list_tags

タグと件数

グラフ

resolve_link

[[リンク]] がどのファイルに解決されるか

get_backlinks

このノートへのリンク元と該当行。リンクされていない言及も任意で取得

get_outgoing_links

発リンクとその解決先（wiki / markdown / 埋め込み / frontmatter）

graph_neighbors

BFS で N-hop 近傍（in / out / both）

find_unresolved_links

存在しないノートへのリンクを、リンク先ごとにまとめる

find_orphans

どこからもリンクされていないノート

書き込み

write_note

新規作成（上書きには overwrite=true が必要）

append_to_note

ノート末尾、または見出しセクションの末尾に追記

edit_section

見出しセクションの置換・先頭挿入・末尾挿入（"親 > 子" 指定可）

replace_in_note

完全一致の置換（出現回数が一致しなければ失敗する）

update_frontmatter

プロパティの追加・削除（コメントや他のキーは保持）

ノートの指定は、パス（folder/note.md）・ノート名（Note Name）・エイリアスのどれでもよい。

安全策

  • .obsidian/ など . で始まるパスは読み書きとも不可（LiveSync の認証情報を守るため）。Vault 外への脱出（.. やシンボリックリンク）も拒否する

  • 書き込めるのは .md だけ。OBSIDIAN_MCP_WRITE_PATHS でフォルダを限定できる。CLAUDE.md / AGENTS.md は常に書き込み不可

  • 編集系ツールは楽観ロックを行う。読み込み後にノートが変わっていたら失敗する（expected_hash を渡すと read_note の時点を基準にできる）

  • 書き込みは隠し一時ファイルに書いてから rename する（アトミック）

  • 削除と移動のツールは意図的に実装していない。livesync-cli の mirror はディスク上の削除を反映せず、ファイルを復元してしまうため（削除は livesync-cli rm で行う）

リンク解決のルール（Obsidian 準拠）

  • folder/Note はパスの完全一致、なければ末尾一致

  • 素の Note は同じフォルダ → ルートに近いもの → 浅いパスの順で優先。候補が複数あるときは ambiguous として列挙する

  • ./ ../ は相対パスとして解決する。#見出し と #^block は subpath として保持する

  • [[エイリアス]] はグラフ上は未解決として扱う（Obsidian と同じ）。ツール引数でノートを指定するときだけエイリアスでも引ける

  • コードブロック、インラインコード、%%コメント%%、<!-- -->、$$数式$$ の中のリンクとタグは無視する

開発

pnpm install
pnpm test          # ユニットテスト + HTTP 経由の e2e
pnpm typecheck
OBSIDIAN_VAULT_PATH=~/vault OBSIDIAN_MCP_READONLY=1 pnpm start

サーバーへのデプロイ

以下は Debian / Ubuntu 系の Linux を想定。LiveSync の CouchDB に到達できる場所に置く。

1. Node.js 24 以上とユーザーの用意

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash - && sudo apt-get install -y nodejs git curl
sudo useradd --system --create-home --home-dir /var/lib/obsidian --shell /bin/bash obsidian
sudo mkdir -p /srv/vault && sudo chown obsidian: /srv/vault

2. livesync-cli（CouchDB から /srv/vault へのミラー）

Self-hosted LiveSync プラグインの作者（vrtmrz）が同じリポジトリ（vrtmrz/obsidian-livesync の src/apps/cli）で公開している CLI を使う（Obsidian 公式のツールではない）。livesync-bridge は E2EE 環境で復号に失敗する不具合が未解決なので使わない。

sudo -iu obsidian
git clone https://github.com/vrtmrz/obsidian-livesync.git ~/obsidian-livesync
cd ~/obsidian-livesync && bash src/apps/cli/deploy/install.sh --vault /srv/vault

他の端末の Obsidian で「Self-hosted LiveSync → Setup → Copy the current settings to a setup URI」を実行し、Setup URI を作る。それを CLI に取り込む（パスフレーズは標準入力で渡す）。

livesync-cli /srv/vault setup "obsidian://setuplivesync?settings=..."

  • E2EE のパスフレーズは他の端末と完全に一致させること。違っていても警告なしに同期が壊れる。パス難読化も同じパスフレーズから導出される

  • 最初は CouchDB への書き込みを避け、livesync-cli /srv/vault mirror を一回だけ実行して /srv/vault の中身を確認するのが安全

  • 一時ファイルを確実に除外するため、/srv/vault/.livesync/ignore に次を書いておく

    .*.tmp

3. obsidian-vault-mcp

sudo git clone https://github.com/asann3/obsidian-vault-mcp.git /opt/obsidian-mcp
cd /opt/obsidian-mcp && sudo corepack enable && sudo pnpm install --prod
sudo cp deploy/obsidian-mcp.env.example /etc/obsidian-mcp.env && sudo chmod 600 /etc/obsidian-mcp.env
sudo sed -i "s/^OBSIDIAN_MCP_TOKEN=.*/OBSIDIAN_MCP_TOKEN=$(openssl rand -hex 32)/" /etc/obsidian-mcp.env
sudoedit /etc/obsidian-mcp.env                 # ALLOWED_HOSTS を公開するホスト名に
sudo cp deploy/obsidian-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now obsidian-mcp
curl -s localhost:8787/healthz

4. HTTPS で公開する

サーバーは 127.0.0.1 だけで待ち受ける。TLS はリバースプロキシで終端する。Tailscale なら次のとおり。

sudo tailscale serve --bg 8787
tailscale serve status        # https://<ホスト名>/ → 127.0.0.1:8787

5. クライアント登録（Claude Code）

claude mcp add --transport http --scope user obsidian https://<ホスト名>/mcp --header "Authorization: Bearer <TOKEN>"

claude.ai / スマホから使う場合

claude.ai のコネクタは、Anthropic のクラウドからサーバーに接続する。そのため、インターネットから届く URL（Tailscale Funnel など）が必要になる。認証は次のどちらか。

  • リクエストヘッダー方式（ベータ）：コネクタの追加画面で、認証を「サインインなし」にして、authorization: Bearer <トークン> を登録する。このサーバーの Bearer 認証がそのまま使える。この項目が表示されないアカウントもある

  • OAuth 2.1：未実装。OAuthTokenVerifier を差し替えて、PRM / AS メタデータ、PKCE、CIMD または DCR を実装する必要がある

公開するときは、読み取り専用にするか OBSIDIAN_MCP_WRITE_PATHS で書き込み先を絞ること。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Obsidian MCP Server

    quinny1187
    A
    license
    B
    quality
    D
    maintenance
    Enables direct file system access to Obsidian vaults with auto-discovery, full-text search, and note operations. Supports reading, writing, and searching across Obsidian notes without requiring plugins or REST API.
    6
    3,445 npm
    MIT

  • Obsidian MCP Server

    igorilic
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to interact with Obsidian vaults for creating, reading, searching, and managing notes, daily notes, TODOs, session reports, and backlinks through both stdio and HTTP/SSE transports.
    10
    3,445 npm
    4
    MIT

  • Obsidian MCP Local

    HenriqueCSouzza
    A
    license
    C
    quality
    D
    maintenance
    Enables AI assistants to search, read, create, and modify Markdown notes in local Obsidian vaults directly through filesystem operations. Supports tag-based discovery and frontmatter parsing without requiring Obsidian to be open, facilitating integration with VS Code Copilot via stdio transport.
    5
    9 npm
    4
    MIT

  • Obsidian MCP Server

    Piotr1215
    F
    license
    Not graded
    quality
    A
    maintenance
    Provides secure, direct file system access to Obsidian vault files, enabling search, read, write, and discovery of notes without requiring the Obsidian app.
    23
    -