Skip to main content
Glama
obsidian-vault-mcp

obsidian-vault-mcp

by Lithial

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: telos-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

Tool

Description

list_projects

List all projects in the vault

write_feature_doc

Write a feature doc under a project (optional tags, links)

list_features

List feature docs, optionally filtered by project and/or tag

write_bug

File a new bug under a project (optional tags, blocked_by, ticket_type)

get_next_bug

Get the highest-priority open bug

get_note

Read a bug or feature note's full frontmatter and content by path — bug vs. feature is auto-detected from the note's own type field

update_note

Update a bug or feature note in place by path (type auto-detected). content replaces the body (omit to leave it unchanged — this also covers a status-only update); tags/links apply to either kind; status/blocked_by/ticket_type are bug-only and rejected against a feature note

list_bugs

List bugs filtered by project, status, tag, and/or unblocked

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>.md

Available Tools

9 tools
get_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

    A3.6/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers