MCP Vault Bridge

MCP Vault Bridge connects Obsidian to MCP clients such as Claude Desktop and LM Studio. It lets an assistant search, read, summarize, organize, and optionally edit the notes you choose to expose.

The bridge is local, token-protected, and read-only by default.

Quick Start

1. Install MCP Vault Bridge from Obsidian Community Plugins, or download the latest zip from Releases.
2. Enable the plugin in Obsidian.
3. Open the plugin settings.
4. Click Check runtime.
5. Click Install SQLite runtime.
6. Copy the generated MCP client config from the plugin settings into Claude Desktop, LM Studio, or another MCP host.
7. Restart or reload your MCP client.
8. Ask the client: Refresh my Obsidian vault index.

Then try prompts like:

• "What notes do I have in my vault?"
• "Find notes about project planning."
• "Read Projects/Roadmap.md and summarize it."
• "What themes appear across my notes?"

What It Can Do

• Read and summarize notes.
• List notes by folder, tag, path, or metadata.
• Search note text.
• Answer broad questions across the vault.
• Show links, backlinks, tags, aliases, and related notes.
• Use optional semantic search with local embeddings.
• Use optional write tools to create and edit Markdown notes.
• Create Obsidian Bases (.base) for folders, tags, file lists, custom filters, or the whole vault.

Connect A Client

Prefer the generated config in the Obsidian plugin settings. It includes the correct token, bridge URL, and local runtime path.

Manual config shape:

{
  "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"
      }
    }
  }
}

Use a full absolute path for mcp-server.cjs. Keep Obsidian open while the MCP client is using the vault.

Main Tools

Most users do not call tools by name. The MCP client chooses them from your prompt.

Optional Write Tools

Write tools are disabled by default. Enable Enable write tools in the Obsidian plugin settings only for MCP clients you trust.

Write tools only modify non-excluded Markdown notes and .base files. They do not expose file deletion or shell commands.

Obsidian Bases

Use create_base_file for prompts like:

• "Create a base file for the Science folder inside Articles."
• "Create a base for notes tagged #book."
• "Create a table for these files with title, author, URL, and date."
• "Create a base in the root of the vault for everything in the vault."

Base behavior to know:

• Every base needs an explicit scope: folder, files, tag, filter, or whole vault.
• If a prompt mentions a folder by name, the client should resolve the real path first with vault_status or list_notes.
• Folder bases are created inside the resolved folder by default. Articles/Science becomes Articles/Science/Science.base.
• Missing folders are created only when the request clearly asks for a new folder.
• Generated bases exclude .base files by default so a base does not list itself.
• Columns, filters, sorting, formulas, summaries, and views can be translated into the generated .base file.

Privacy Basics

• Read-only by default.
• Token-gated local bridge on 127.0.0.1.
• User-configured excluded folders, files, and tags are hidden from tools.
• Hidden folders, .obsidian, .trash, .git, and path traversal are always blocked.
• No telemetry.

MCP hosts may send tool results to their model. Claude Desktop runs the MCP server locally, but Claude model calls are cloud-side. LM Studio can remain fully local when both chat and embeddings use local models.

See Security Notes for more detail.

Exclusions And Indexing

Regular Markdown notes are included by default. In plugin settings, you can exclude:

• folders,
• exact file paths,
• tags.

After changing exclusions, click Refresh preview in Obsidian, then ask your MCP client to run refresh_index.

The SQLite index is a rebuildable cache. Your Obsidian notes remain the source of truth.

Optional Semantic Search

Without embeddings, search uses local SQLite full-text search. This is fast and works well for exact words, titles, folders, tags, and phrases.

With embeddings, search can also find related ideas when the same words are not used. Local LM Studio embeddings are a good privacy-preserving setup.

See LM Studio with embeddings for setup.

Troubleshooting

Environment Variables

Most users only need the generated client config. These variables are available for manual setups:

Development

npm install
npm run build
npm test
npm run typecheck
npm run lint
npm run lint:obsidian

Install a development build into a local vault:

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

See CONTRIBUTING.md for branch conventions and release steps.

License

MIT