allexcd_obsidian-mcp/README.md

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. Download the latest mcp-vault-bridge-X.Y.Z.zip from the Releases page.
2. Unzip and copy the complete 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.

From source

npm install
npm run build   # builds all packages + the standalone 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"
      }
    }
  }
}

For semantic search, add an embedding model and three extra env vars — see LM Studio with embeddings.

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.

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