obsidian-vault-mcp
Manages feature documentation and bug tracking inside an Obsidian vault, organized by project.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-vault-mcp list my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildRelated MCP server: telos-mcp
Configuration
Set VAULT_PATH to the root of your Obsidian vault:
VAULT_PATH=/path/to/vault node dist/index.jsomp 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
Tool | Description |
| List all projects in the vault |
| Write a feature doc under a project (optional |
| List feature docs, optionally filtered by project and/or |
| File a new bug under a project (optional |
| Get the highest-priority open bug |
| Read a bug or feature note's full frontmatter and content by path — bug vs. feature is auto-detected from the note's own |
| Update a bug or feature note in place by path (type auto-detected). |
| List bugs filtered by project, status, |
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_note 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>.mdAvailable Tools
9 toolsget_bugA
Read the full content and metadata of a bug note by its file path
Inputs: path (required).
get_feature_docA
Read the full content and metadata of a feature document by its file path
Inputs: path (required).
get_next_bugB
Get the highest-priority open bug, optionally scoped to one project
Inputs: project.
list_bugsA
List bugs in the vault, optionally filtered by project and/or status
Inputs: status, project.
list_featuresA
List feature documents in the vault, optionally scoped to one project
Inputs: project.
list_projectsA
List all project names in the Obsidian vault
Inputs: no named parameters.
update_bug_statusB
Update the status of a bug note by its file path
Inputs: path (required), status (required).
write_bugC
File a new bug in the vault under a specific project
Inputs: title (required), description (required), project, priority, +2 more.
write_feature_docB
Write a feature document to the vault under a specific project
Inputs: title (required), content (required), project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct operation on either bugs or features, with no overlap. Bug tools are separated by function (create, read by path, list, get highest priority, update status), and feature tools are similarly distinct.
All tool names consistently follow the verb_noun pattern using snake_case, e.g., list_bugs, write_feature_doc, update_bug_status. No mixed conventions or vague verbs.
9 tools is well-scoped for a project management vault MCP, covering both bugs and features with essential operations. The number feels neither too thin nor excessive.
Bugs have create, read (multiple forms), and update status, but no delete. Features have create and read, but no update or delete. These are notable gaps that could hinder agent workflows requiring full lifecycle operations.
Maintenance
Related MCP Connectors
Issue tracking for software projects: issues, epics, releases, docs and boards, from your AI.
Personal project management with AI agents: numbered tickets, statuses, files, a thread per ticket.
Personal project management with AI agents: numbered tickets, statuses, files, a thread per ticket.
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables comprehensive management of Obsidian vaults with full CRUD operations, advanced search, link/tag extraction, backlinks discovery, frontmatter editing, and template-based note creation through natural language.16MIT
- AlicenseBqualityDmaintenanceTask planning and tracking for AI agents with project-based organization and Obsidian-compatible markdown storage.1311 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to store and retrieve project context, bugs, decisions, and session logs by reading and appending markdown files in a local Obsidian vault, without requiring any cloud services.6MIT
- FlicenseBqualityAmaintenanceA local, file-backed feature/bug board for projects, enabling Claude to read and write markdown boards (featurelist.md / buglist.md) directly in chat for task planning, bug logging, and velocity tracking.2172-