obsidian-vault-mcp

A stdio MCP server for managing feature documentation and bug tracking inside an Obsidian vault, organised by project.

Setup

npm install
npm run build

Related MCP server: Obsidian MCP

Configuration

Set VAULT_PATH to the root of your Obsidian vault:

VAULT_PATH=/path/to/vault node dist/index.js

omp Registration

Add to ~/.omp/agent/mcp.json:

"obsidian-vault": {
  "command": "node",
  "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"],
  "env": { "VAULT_PATH": "/path/to/your/obsidian/vault" }
}

Tools

Relational frontmatter fields

Bugs and feature docs both accept optional tags: string[] (grouping labels, e.g. ["wf:payments-v2-migration"]) and links: string[] (absolute paths to related vault notes — e.g. pairing a resolved ticket with the note that recorded its answer).

Bugs additionally accept blocked_by: string[] (absolute paths to bug notes that must reach a terminal status — resolved or out-of-scope — before this one is workable) and ticket_type: string (descriptive only, e.g. research, grilling, task). list_bugs computes an unblocked field per bug and supports unblocked: true to filter to the frontier (open + not blocked). None of these fields are validated for existence — callers are trusted, matching shortcut_card/shortcut_branch.

A bug note's file path never changes across status transitions — update_bug_status only rewrites frontmatter, never moves the file — so a blocked_by reference recorded while the blocker is open stays valid once it resolves. (Earlier versions relocated resolved/out-of-scope bugs into a Bugs/Resolved/ subfolder; this broke blocked_by when the blocker moved out from under an existing reference. list_bugs still scans Bugs/Resolved/ recursively for backward compatibility with any notes relocated before this fix, but no new relocations happen.)

Vault Layout

<vault>/
  Projects/
    <ProjectName>/
      Features/<slug>.md
      Bugs/<slug>.md