Obsidian

Obsidian

Full read/write access to a user's Obsidian vault through the Local REST API community plugin. The vault is a folder of Markdown files with YAML frontmatter, wikilinks, and hierarchical tags.

Data Model

• Notes are .md files at paths relative to the vault root (e.g. Projects/my-project.md).
• Frontmatter is YAML at the top of a note between --- fences. Returned as parsed JSON. Contains metadata like tags, aliases, dates, and custom fields.
• Tags use #tag syntax inline or tags: in frontmatter. Hierarchical: #project/active rolls up to #project.
• Wikilinks ([[Note Name]]) create internal links. Always use wikilinks when referencing other notes in content you write.
• Daily notes are the most common Obsidian workflow. Reading today's periodic daily note is the fast path. The Periodic Notes plugin supports weekly, monthly, quarterly, and yearly notes too.
• Block references (^blockid) let you target specific paragraphs for PATCH operations.
• Commands are any Obsidian action (open graph view, insert template, export to PDF, etc.) identified by an ID like graph:open.

Key Patterns

• Read before write: Always read a note before modifying it to understand its structure.
• PATCH for surgical edits: Patch a note to insert content at a specific heading, block reference, or frontmatter field without overwriting the whole note.
• Document map: Read a note with format=map to discover available headings, block refs, and frontmatter fields before PATCHing.
• Daily note append: The most common operation — append a thought, task, or log entry to today's daily note.
• Search then act: Search for notes, then read/modify them.
• Image reading: Read vault images (PNG, JPEG, GIF, WebP, BMP, SVG) into the AI conversation. The image is returned as visual content the AI can see and analyze — useful for describing diagrams, reading handwritten notes, or referencing screenshots.

Runtime requirements

• Obsidian must be running on the user's machine with the Local REST API community plugin installed and enabled.
• The plugin exposes an HTTPS server on port 27124 by default (self-signed cert, handled by the proxy).
• MCPBundles Desktop must be running so this bundle can reach the user's machine. Download at https://www.mcpbundles.com/desktop. Plugin install and credential setup are handled in the MCPBundles credential form, not by the agent.

Gotchas

• Writes are live: Every write mutates the user's real vault immediately. There is no undo via the API.
• Plugin must be running: Obsidian must be open with the Local REST API plugin enabled. If Obsidian is closed, all tools will fail with a connection error.
• Paths are relative: All file paths are relative to the vault root. No leading slash.
• Note path parameter: Vault note tools use filename= (e.g. Projects/note.md). Only directory listing uses path= for folders.
• Directory listing root: Omit path to list the vault root. Do not pass path="/" — that returns 404 from the plugin.
• Trailing slashes on directories: Non-root directory listing paths must end with /.
• Daily notes: Reading today's daily note errors if it does not exist yet. Append to today's daily note to create from template or add content without a prior read.
• Concurrent writes: Parallel appends or patches to the same file can reorder or corrupt content — serialize edits per note.
• Deletes are permanent: Deleting a note removes real vault files with no API undo — never target production notes in tests.
• Property search: Use property_name, operator, and optional value — not property.
• Date search: Use days_ago and date_type (modified or created) — not days or field.
• Dataview requires plugin: Advanced search with DQL queries requires the Dataview community plugin installed in Obsidian.
• Periodic Notes plugin: Weekly/monthly/quarterly/yearly periodic notes require the Periodic Notes community plugin. Daily notes work with either Periodic Notes or the core Daily Notes plugin.