MCP Vault Bridge

Read-only by default Obsidian vault bridge for MCP clients — connect Claude Desktop and LM Studio to your notes with exclusion-based privacy controls, optional semantic search, and opt-in write tools.

Security

• Read-only by default. Write tools are disabled unless you explicitly enable them in the Obsidian plugin settings.
• Token-gated. The bridge only accepts requests with the bearer token generated by the plugin.
• Exclusion-based. Folders, files, and tags can be excluded before connecting any MCP host.
• Always denied. Hidden folders, .obsidian, .trash, .git, and path-traversal patterns are blocked regardless of exclusions.
• Write scope is narrow. Optional write tools only create or edit non-excluded Markdown notes; they do not delete files or run commands.
• Embeddings off by default. When enabled, note chunks are sent to your configured embedding endpoint — use a local model (LM Studio, Ollama) to keep everything on-device.
• No telemetry.

Vault content returned by MCP tools may be forwarded to the model by the host. Claude Desktop runs the MCP server locally, but Claude model calls are cloud-side. LM Studio can remain fully local with local chat and embedding models.

When write tools are enabled, any MCP host with the bridge token can modify included notes. Only enable writes for trusted local clients.

Install

End users

1. Install MCP Vault Bridge from Obsidian Community Plugins, or download the latest mcp-vault-bridge-X.Y.Z.zip from the Releases page.
2. For zip installs, unzip and copy the mcp-vault-bridge folder into your vault:

   Your Vault/.obsidian/plugins/mcp-vault-bridge/
   

3. Restart Obsidian (or reload community plugins) and enable MCP Vault Bridge.
4. Open the plugin settings, click Check runtime, then Install SQLite runtime.

Node.js 20+ and npm must be available for the runtime install step. If they are missing the settings screen will say so. Obsidian installs only manifest.json, main.js, and styles.css. When the plugin is enabled it creates the local mcp-server.cjs and runtime package.json inside its installed plugin folder. node_modules is created only when you click Install SQLite runtime.

From source

npm install
npm run build   # builds all packages + the community-plugin-shaped plugin folder
npm test        # runs the test suite

To install directly into a local vault for development:

npm run plugin:install -- --vault "/absolute/path/to/Test Vault"

Connect

Claude Desktop

Open the Claude Desktop MCP config (Developer → Edit config) and add:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/Your Vault/.obsidian/plugins/mcp-vault-bridge/mcp-server.cjs"
      ],
      "env": {
        "OBSIDIAN_MCP_BRIDGE_URL": "http://127.0.0.1:27125",
        "OBSIDIAN_MCP_TOKEN": "PASTE_TOKEN_FROM_OBSIDIAN_PLUGIN"
      }
    }
  }
}

Copy the token from the Obsidian plugin settings. Restart Claude Desktop after saving.

Paths: use the full absolute path starting with / on macOS/Linux. Spaces are fine as-is in JSON — do not escape them with \. On Windows, double the backslashes or use forward slashes. Write access: the same token can use write tools when they are enabled in Obsidian. Keep write tools disabled unless this MCP client is trusted.

LM Studio

Add the same config to LM Studio's mcp.json. Without embeddings, vault search uses SQLite full-text search, which is fast and works well for exact words and phrases.

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/Your Vault/.obsidian/plugins/mcp-vault-bridge/mcp-server.cjs"
      ],
      "env": {
        "OBSIDIAN_MCP_BRIDGE_URL": "http://127.0.0.1:27125",
        "OBSIDIAN_MCP_TOKEN": "PASTE_TOKEN_FROM_OBSIDIAN_PLUGIN"
      }
    }
  }
}

Optional embeddings

Embeddings are optional. Without them, search uses SQLite full-text search: it is local, fast, and good for exact words, titles, tags, and phrases. With embeddings enabled, the MCP server can also do semantic/vector search, so queries like “notes about long-term planning” can find notes that use different wording.

Embeddings are cached in the local SQLite index by note chunk content hash. When notes are edited, rewritten, deleted, or later excluded from the vault scope, old chunk vectors can become stale cache data. Pruning removes vectors that are no longer referenced by current indexed chunks; it does not change your Obsidian notes.

Most users do not need to prune manually because Auto-prune embeddings is enabled by default in the plugin settings and runs after note writes and refresh_index. Manual pruning is useful if you disable auto-prune, change exclusions, troubleshoot a large index.sqlite, rebuild/delete index data, or see orphaned embeddings reported by index_status. You can trigger it from Obsidian with Advanced settings → Prune now, or from an MCP client by asking it to run prune_embeddings.

The plugin/MCP server does not automatically know which embedding model LM Studio loaded. The model value must match the identifier exposed by LM Studio's embeddings endpoint. If no embedding model is loaded, search still works through SQLite full-text search, but semantic search and related_notes are unavailable.

For LM Studio, load an embedding model such as nomic-embed-text-v1.5, start the local server, then add these env vars to the same MCP config:

"env": {
  "OBSIDIAN_MCP_BRIDGE_URL": "http://127.0.0.1:27125",
  "OBSIDIAN_MCP_TOKEN": "PASTE_TOKEN_FROM_OBSIDIAN_PLUGIN",
  "OBSIDIAN_MCP_EMBEDDINGS": "on",
  "OBSIDIAN_MCP_EMBEDDING_BASE_URL": "http://127.0.0.1:1234/v1",
  "OBSIDIAN_MCP_EMBEDDING_MODEL": "nomic-embed-text-v1.5"
}

Claude Desktop works the same way: it launches the local MCP server, and that server can call LM Studio's local embedding endpoint if these env vars are configured. Claude model calls are still cloud-side, but embedding calls stay local when they point to LM Studio.

See LM Studio with embeddings for the longer setup guide.

Example prompts

Without embeddings, ask for exact words, paths, tags, folders, and known topics:

• “What notes do I have in my vault?”
• “Find notes tagged #project.”
• “Search my vault for meeting notes.”
• “Read Projects/Roadmap.md and summarize it.”
• “Show backlinks and outgoing links for Ideas/Local AI.md.”

With embeddings enabled, you can ask more conceptual questions because the MCP has a dedicated ask_vault tool and semantic search can find related ideas even when the exact words differ:

• “Search my vault with semantic search for recurring themes.”
• “Find notes related to long-term planning, even if they do not use those words.”
• “What themes keep repeating across my notes about work and focus?”
• “What are the common themes across my notes?”
• “Which notes are conceptually similar to Ideas/Local AI.md?”
• “Find notes that might help me make sense of this project direction.”
• “Summarize the main ideas in my vault about learning, memory, and writing.”

Write Access

Write tools are disabled by default. To allow an MCP client to modify notes, open the Obsidian plugin settings, go to Advanced settings, and enable Enable write tools.

Write tools only operate on regular Markdown notes that are inside the current vault scope. Excluded folders, excluded files, excluded tags, hidden paths, .obsidian, .trash, .git, and traversal-style paths remain denied. Passage edits use exact text matching: if the requested passage is missing, no write happens; if it appears more than once, the tool asks for an occurrence index instead of guessing.

create_note is the only tool that creates Markdown files. Other write tools require an existing included note. File deletion is not exposed.

Vault Scope & Exclusions

The plugin scans the vault through Obsidian and shows detected folders, files, and tags in its settings. Regular Markdown notes are included by default.

Exclusion type	What it hides
Excluded folders	Every note inside a folder, e.g. Private
Excluded files	A single exact path, e.g. Inbox/Secret.md
Excluded tags	Any note carrying a tag, e.g. #private

After changing exclusions, click Refresh preview in the plugin settings, then run refresh_index from your MCP host so the SQLite index reflects the new scope.

When you add or edit notes later, ask your MCP client to refresh the index:

“Refresh the vault index.”

This calls refresh_index, updates SQLite, and refreshes embeddings too if they are enabled.

The SQLite file is a rebuildable cache, not the source of truth. If index.sqlite is deleted, run refresh_index to recreate it; embeddings may need to be recomputed.

MCP Tools

Tool	Description
vault_status	Plugin version, vault name, included note count, scope summary
refresh_index	Rebuild the SQLite index (and embeddings if enabled)
index_status	Index freshness, row counts, embedding state
prune_embeddings	Remove stale cached embedding vectors no longer used by indexed note chunks
ask_vault	Default tool for natural vault questions; uses embeddings automatically when available
analyze_vault	Find candidate notes/snippets for themes, patterns, and vault-wide synthesis
list_notes	Paginated list of included notes with metadata
search_vault	Full-text (or semantic) search across the vault
read_note	Full content of a note by path
get_note_metadata	Frontmatter, tags, aliases, links for a note
get_note_links	Outlinks, embeds, and backlinks for a note
related_notes	Notes semantically similar to a given note (requires embeddings)
create_note	Create a new non-excluded Markdown note; can overwrite only when explicitly requested
append_note	Append Markdown content to an existing included note
replace_note_text	Replace exact text in an existing included note; duplicate matches require occurrenceIndex
delete_note_text	Delete exact text from an existing included note; duplicate matches require occurrenceIndex
rewrite_note	Replace all content in an existing included note; empty content is allowed

All tools return JSON text. Note content is marked untrusted so hosts do not treat it as instructions. Write tools require the Obsidian write setting to be enabled and are limited to non-excluded Markdown notes.

Environment Variables

Variable	Default	Description
OBSIDIAN_MCP_BRIDGE_URL	http://127.0.0.1:27125	Obsidian bridge URL
OBSIDIAN_MCP_TOKEN	—	Required. Bearer token from the plugin settings
OBSIDIAN_MCP_DB	plugin folder index.sqlite	Override the SQLite cache path
OBSIDIAN_MCP_MAX_RESULTS	20	Default result cap for list/search tools
OBSIDIAN_MCP_AUTO_PRUNE_EMBEDDINGS	plugin setting, usually on	Override automatic stale embedding pruning
OBSIDIAN_MCP_EMBEDDINGS	off	Set to on to enable semantic search
OBSIDIAN_MCP_EMBEDDING_BASE_URL	—	OpenAI-compatible endpoint, e.g. http://127.0.0.1:1234/v1
OBSIDIAN_MCP_EMBEDDING_API_KEY	—	Optional API key for the embedding endpoint
OBSIDIAN_MCP_EMBEDDING_MODEL	—	Embedding model name

Contributing & Release

See CONTRIBUTING.md for branch/commit conventions, how to run checks locally, and how to cut a release. The pre-push hook (activated automatically by npm install) enforces naming conventions; CI re-checks them on every PR.

License

MIT