headless-obsidian-mcp: Instructions file for Claude Code

Headless Obsidian MCP

This is a headless MCP (Model Context Protocol) server for interacting with Obsidian vaults. It provides tools to search, read, navigate the link graph, and edit notes in an Obsidian vault — without the Obsidian GUI.

Development workflow

Anything beyond trivial work (a single-line fix or a pure question) should be done in a git worktree, so parallel development tasks stay isolated from each other and from the main checkout. Trivial changes may be made in place.

Design records

Design specs (brainstorming output) go in design/specs/, implementation plans (writing-plans output) in design/plans/ — not the superpowers skills' default docs/superpowers/, which this project does not use. Keep the skills' YYYY-MM-DD-<topic>-design.md / YYYY-MM-DD-<feature-name>.md filenames. docs/ is reserved for user-facing reference (docs/CLI.md, docs/TOOLS.md); design/ is contributor-facing.

These records are written before implementation and are not maintained afterwards — they capture why a decision was made, not what the code currently does. CLAUDE.md and README.md are the current source of truth; a spec that disagrees with them is stale, not authoritative.

Setup

1. Set the OBSIDIAN_VAULT_PATH environment variable to point to your Obsidian vault directory
2. Ensure ripgrep (rg) is installed on your system
3. Install dependencies and build: npm install && npm run build
4. Run with: npm start or mise run start (if using mise)

Tools

Naming conventions

Tool names follow a fixed verb taxonomy. A new tool reuses an existing verb; it does not coin a synonym. The verb encodes the tool's scope and addressing so an agent can predict behavior from the name alone.

• get_ — return one addressed thing: a note by path (get_links, get_outline, get_frontmatter, get_property, get_related_notes), or the vault as a single object (get_vault_stats). A collection-valued return is fine when it is about one addressed note (get_related_notes); it is not get_ when it enumerates a vault-wide collection — that is list_.
• list_ — enumerate a vault-wide collection, optionally scoped or parameterized: list_notes, list_files, list_folders, list_tags, list_properties, list_property_values, list_recent_notes, list_vault_issues. A required argument does not demote it to get_ (list_property_values(key), list_vault_issues(kind)).
• search_ — text query over content (search_notes, search_notes_ranked). read_ — return body text from disk (read_notes, read_section). resolve_ — map a human name to a canonical path (resolve_note, resolve_daily_note — a date is a human-facing name too).
• find_by_X — retrieval by one named criterion (find_by_tag). query_ — retrieval by a condition object (query_notes); where is the single condition language, anchored by query_notes, and reused verbatim by every tool that filters notes.
• Writes name the mutation: write/append/prepend/delete/move, add/remove_tag, set_frontmatter, add/remove_property_values, rename_property, add/append_to/replace_section, patch_note, bulk_edit. The _property_values noun is per-note when prefixed add_/remove_ (writes) and vault-wide when prefixed list_ (read) — the verb, not the noun, carries the scope. create_ is the folder-only create verb (create_folder): write_ implies content, which a folder has none of, so a folder's creation is named for what it actually does. On folders the mutation verbs otherwise carry over unchanged (move_folder, delete_folder).