MCP Vault Bridge

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

Security

• Read-only. No write, delete, shell, or command-execution tools exist.
• 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.
• 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.

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.

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.

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.”

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.

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
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)

All tools return JSON text. Note content is marked untrusted so hosts do not treat it as instructions.

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_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