Obsidian Vault MCP

A local desktop VS Code extension and MCP server for using Obsidian knowledge while coding. Independent project, not an official Obsidian product.

Install and start

1. In desktop VS Code 1.103+, run Extensions: Install from VSIX... and select obsidian-vault-mcp-0.5.0.vsix.
2. The extension reads Obsidian's own registered-vault list. It selects the only registered vault or the uniquely open vault; it does not scan the computer for Markdown files.
3. To select a vault explicitly, run Obsidian MCP: Switch Vault. This pins your choice and disables auto-detection until you re-enable it in settings.
4. Open a trusted coding workspace, then use MCP: List Servers to start and trust Obsidian Vault. Enable its tools in agent chat.
5. Writes are off by default. Enable obsidianVault.enableWrites if wanted and restart the server. Existing users' chosen write permissions are retained.

The packaged extension uses VS Code's Node runtime; no separate Node installation is needed. VS Code Web is unsupported. The extension is designated to run locally in Remote SSH/WSL/container scenarios; vaults must be accessible on the desktop.

Capabilities

The nine preview/apply/cancel tools are only registered with writes enabled. Every result identifies the selected vault and its stable vaultId. Optional vaultId inputs on reads/previews reject unexpected targets. Apply requires the exact vaultId, proposalId and expectedRevision from its preview.

Search, properties and exact excerpts

• Keyword search supports all-term matching, exact phrases, folder, tag, heading, and exact frontmatter-property filters. Results include paths and line ranges.
• query_notes filters exact property values, folder and tags without requiring a keyword. It never evaluates JavaScript or Dataview queries.
• Read a whole note with pagination or retrieve a unique heading/block ID. Ambiguous names/headings are errors, not guesses.
• get_project_context collects bounded one-hop linked/backlink notes.
• Health checks suggest repairs for broken links/anchors, orphan notes, duplicate titles and missing required properties. Nothing is auto-deleted.

Examples:

Find active project notes under Projects, then read the Decisions section.

List unfinished tasks for this project and preview completing the first one.

Check for broken links and notes missing the status property. Suggest fixes.

Editing, visual review and undo

preview_note_edit supports:

• replace_note: replace the entire Markdown content.
• replace_section: retain a unique heading and replace its section body.
• replace_text: replace an exact string that occurs once.
• properties: set/remove frontmatter keys while retaining YAML comments where possible.

Text/property edits require the latest note revision from read_note. Task updates require the exact line and revision from list_tasks. The existing append tool still supports a note, unique section, or daily date.

1. Ask the agent to prepare a preview and show all changed files and target vault.
2. Run Obsidian MCP: Review Pending Changes for side-by-side VS Code diffs.
3. Choose Apply Reviewed Changes, Cancel Proposal, or Keep Pending. The agent can also apply after your approval through the MCP confirmation flow.
4. Run Obsidian MCP: Undo Change to preview restoring an applied operation.

Previews are vault-bound, expire after ten minutes, and survive server restarts. They live under .obsidian-mcp/proposals. Complete before/after snapshots, operation status and backups live under .obsidian-mcp/history and backups. These hidden folders are excluded from note tools. Backups/history remain until you remove them; expired proposal files are pruned when preparing new ones.

Undo is itself a preview and needs approval. It refuses if any affected note has changed since the operation. Undoing creation removes only the unchanged file that operation created. There is no arbitrary delete or automatic cleanup tool. Old version 0.2 backups remain in .obsidian-mcp-backups; they are not migrated into the new operation history.

Rename and move

File-mode rename previews changes to the note and references across indexed notes. It retains wikilink aliases, heading anchors and basic Markdown links, adjusts outgoing relative references, and ignores common fenced/inline code. It supports undo using the same operation history.

It is a lightweight Markdown implementation, not complete Obsidian parser parity. Excluded notes and attachments are not indexed for incoming links. Case-only renames are rejected. Review all changed files before applying. For Obsidian's exact internal behavior, use native: true with the companion.

Templates, daily notes and session capture

By default, tools read .obsidian/templates.json and daily-notes.json to use your actual Templates folder, daily-note folder, date format and template. Without these files, defaults are Templates, Daily, and YYYY-MM-DD. Set useObsidianSettings to false to use extension defaults.

Template variables support {{title}}, {{date}}, {{date:FORMAT}}, {{time}}, {{time:FORMAT}}, and explicit user variables. Date/time formatting uses Moment tokens. Missing variables fail explicitly. Templates do not execute Templater scripts or arbitrary code.

preview_session_capture takes an explicit summary, date, decisions, changed file references and follow-up tasks. It previews a structured append; it does not monitor chats, git, or editors in the background.

Explicit vault targeting

The registry is Obsidian's application-maintained obsidian.json (Windows: %APPDATA%\obsidian\obsidian.json; macOS: Application Support; Linux: XDG config). Its saved open flag is not a live application connection.

switch_vault accepts a registered vaultId and switches this MCP session only. It does not change VS Code settings, move previews, or retarget existing edits. To review a proposal in another vault, switch the extension to that same vault. Applying with a mismatched vault ID fails.

An MCP process stays bound to its selection until explicitly switched or restarted; it never silently redirects a pending write because Obsidian changed the active vault. Obsidian MCP: Switch Vault pins the extension's selection.

Optional live Obsidian companion

The VSIX bundles a separate desktop Obsidian plugin. It is not installed or enabled in your vault automatically.

1. Run Obsidian MCP: Install Companion Plugin in VS Code.
2. Review the target vault and confirm installation.
3. In Obsidian, reload plugins and enable Obsidian Vault MCP Companion under Community plugins (Restricted Mode must permit community plugins).
4. Keep Obsidian open for live context and native renames. Obsidian does not need to be open for any other tool.
5. For native renames, enable Allow confirmed vault renames in the plugin's settings too. Each native apply additionally displays a confirmation in Obsidian.

The plugin serves bounded current-note and selected-text context, resolves links through Obsidian's live metadata cache, and delegates confirmed renames to Obsidian's file manager. It binds only to 127.0.0.1 on a random port, uses a random bearer token, and rejects browser Origin headers.

When the companion is not running (no descriptor, or a stale one after a crash), resolve_obsidian_link resolves from the file index instead and reports resolver: "files". That mode strips #heading/|alias parts, accepts aliases, rejects ambiguous note names rather than choosing one, and resolves Markdown notes only. Companion results report resolver: "obsidian". Security and not-found errors from a running companion are never masked by the fallback.

The connection descriptor is .obsidian/plugins/obsidian-vault-mcp/bridge.json. Keep it private. The plugin removes its own descriptor on unload and checks for a stale crashed instance on startup. It never exposes an unauthenticated HTTP API.

Native rename previews are explicitly pre-rename snapshots and scope, not predicted post-rename diffs: Obsidian applies links according to its automatic link-update setting. Native proposals are limited to 32 affected Markdown notes and 1 MB of snapshots, and destination folders must already exist. Changed revisions/scope are rejected. Native backups live inside the companion plugin's backups directory; they are separate from file-mode history/undo. Native rename failures report recovery locations and rollback status. Native undo is performed by previewing the reverse native rename or restoring those backups.

Standard .obsidian configuration directories are supported by the VS Code discovery client/installer. Custom Obsidian config directories are not yet supported there. The bundled companion README contains manual installation and protocol details.

Optional semantic search (local embeddings)

Semantic search is implemented but disabled until you configure a local model:

1. Install and run Ollama locally, if you choose to use it.
2. Install an embedding model, for example ollama pull nomic-embed-text.
3. Set obsidianVault.semanticSearch.enabled to true and restart the server.
4. Ask for meaning-based retrieval using semantic_search.

The default endpoint is http://127.0.0.1:11434/api/embed. Only literal loopback HTTP endpoints (127.0.0.1 or [::1]) are accepted; redirects are rejected. The extension never installs/downloads models automatically and has no cloud embedding fallback. Chunks and queries are sent to your local service only. Review that service's own retention/security settings.

Embeddings are cached in memory by note revision, up to 500 indexed notes and eight 40-line / 4,000-character chunks per note. Results report index limits and omitted notes. This bounded retrieval is not an exhaustive semantic index of very large vaults. A missing model/service or malformed response is an explicit error. Ordinary search does not use embeddings.

Use the vault as Copilot's instructions source

Keep your coding standards in the vault and have Copilot follow them in every project. Run Obsidian MCP: Use Vault as Copilot Instructions Source (the extension also suggests it once a vault is detected; at most every 30 days).

• The vault's .github/instructions/ folder is linked to ~/.copilot/instructions/obsidian-<vault name>, Copilot's personal instructions folder. On Windows this is a directory junction (no administrator rights). Nothing is copied: edits in the vault apply immediately.
• If the vault has no *.instructions.md files yet, you choose its home/index note and a starter obsidian-vault-knowledge.instructions.md is created. It tells agents to read that note at session start, consult relevant notes, keep the rest as "check back later", and propose capturing reusable rules in the vault. Obsidian hides .github, so edit instruction files in VS Code.
• Files with applyTo globs apply automatically to matching files in every project (for example **/*.py); files without one load when their description matches the task. Review applyTo: "**/*.md"-style rules that were written only for the vault itself.
• The vault's own .github/copilot-instructions.md is not linked; it still applies only when the vault is the open workspace.
• Obsidian MCP: Stop Using Vault as Copilot Instructions Source removes only the link. Existing folders or links at that path are never replaced.

Anyone who can edit the vault folder (for example a shared OneDrive or SharePoint library) can change Copilot's instructions in all your projects. ~/.copilot/instructions is read by Copilot CLI and the Copilot agent harness in VS Code; start a new chat session after setup.

Settings

All settings use the user/application scope, not workspace-controlled vault access.

Restart MCP after changing settings. Tool paths are vault-relative with / separators, even on Windows. Vault roots are absolute OS paths.

Agents windows and standalone clients

Some agent-session windows don't activate third-party extension providers. Use MCP: Open User Configuration and add a stdio entry under servers:

• command: absolute Node.js 22+ executable path.
• args: an array with the installed extension's absolute dist/server.cjs path.
• env.OBSIDIAN_MCP_OPTIONS: JSON-encoded object, for example {"autoDetectVault":true,"enableWrites":true,"useObsidianSettings":true}.

You may pin root instead of auto-detecting. Other options include excludedFolders, dailyNotesFolder, and embeddings: {enabled, endpoint, model}. This entry is independent of extension settings: update write/model settings and the installed server path separately. If no unique initial selection exists, configure root explicitly.

Avoid enabling both the manual server and extension provider in one chat. Proposals/history are shared on disk, so the VS Code review commands can review file-mode previews prepared by either server when both target the same vault.

Safety, persistence and limitations

• File tools have no HTTP listener; only the optional companion and explicitly enabled local embeddings use loopback networking.
• Only selected-vault Markdown is exposed. Traversal, symlinks/junctions, hidden paths, reserved filenames and configured excluded folders are rejected. Hidden Obsidian settings/companion/state files are accessed only by dedicated, narrowly scoped code, not generic note tools.
• Notes/selections are untrusted data. Agent instructions are not a guarantee against every prompt-injection attempt.
• Content returned to an AI agent may be sent to its configured model service. Local note storage does not mean local-only AI inference.
• Preflight revisions, per-vault MCP locks, atomic replacement of existing notes, backups and rollback protect against common conflicts. Obsidian/sync tools do not share the MCP lock; avoid editing the same notes during apply. Multi-file edits are not filesystem-wide atomic transactions.
• Failed operations are recorded. Rollback refuses to overwrite unexpected concurrent changes and reports incomplete recovery. On process/power failure, inspect pending history, backups and .obsidian-mcp/apply.lock before removing a stale lock. Keep independent vault backups.
• Indexing refreshes before reads and reuses unchanged contents. Notes over 1 MiB are skipped and reported; malformed YAML and filesystem errors are explicit.
• No automatic deletion, background AI rewrites, remote embeddings, Dataview evaluation, arbitrary command execution or attachment-text extraction.

Develop, validate and package

Requires Node.js 22+ and npm:

npm ci
npm --prefix companion ci
npm run check
npm run package

Builds bundle the extension, server and companion. Tests use disposable fixture vaults, a local mock embedding API, and mocked VS Code/Obsidian UI contracts. They verify real stdio/HTTP communication, review/apply/undo, revisions, rollback, queries, templates, tasks and vault switching. Interactive desktop behavior and your actual Ollama model remain manual acceptance checks.

Press F5 for a VS Code Extension Development Host.

Publish

The VSIX is installable locally without publishing credentials. To publish:

1. The publisher in package.json is the Marketplace publisher ID GuillaumePrvost (shown at https://marketplace.visualstudio.com/manage).
2. Make https://github.com/Ratiomachinium/obsidian_MCP public with this source.
3. Run checks, package, and test in desktop VS Code and Obsidian.
4. Authenticate privately with npx vsce login YOUR_PUBLISHER_ID, then npx vsce publish.

The Obsidian companion is a separate plugin; bundling it does not automatically publish it to Obsidian's community plugin directory.