vault-health-mcp

MCP server for Obsidian vault structural health checks.

Find broken wikilinks, orphaned notes, and missing frontmatter — then auto-repair them. Works with any Obsidian vault, no plugins required.

Install

Terminal

pip install vault-health-mcp

Usage

Claude Code

Terminal

claude mcp add vault-health -- vault-health-mcp --vault ~/my-vault

Claude Desktop

config.json

{
  "mcpServers": {
    "vault-health": {
      "command": "uvx",
      "args": ["vault-health-mcp", "--vault", "/path/to/vault"]
    }
  }
}

MCP Tools

Tool	Tier	Description
`configure_vault`	Free	Point the server at a vault at runtime
`check_vault_health`	Free	Full structural scan: broken links, orphans, missing frontmatter
`find_orphans`	Free	List all structurally disconnected leaf notes
`find_broken_links`	Free	List all wikilinks pointing to non-existent files
`vault_statistics`	Free	File count, link count, orphan %, frontmatter coverage
`repair_vault`	Pro	Auto-fix safe issues (add-only, never deletes)

How auto-repair works (Pro)

repair_vault only makes additive changes:

Broken [[links]] → replaced with plain text (the link text is preserved)
Missing frontmatter → adds a default YAML block with title and type

It never deletes files, removes content, or modifies existing frontmatter values.

Pro tier

The free tier detects every category of vault rot. The Pro tier unlocks repair_vault — one call to fix the safe categories automatically.

License activation — any one of these works:

server.ts

# 1. Environment variable
export VAULT_HEALTH_LICENSE="eyJhbGc..."

# 2. CLI flag
vault-health-mcp --license-key "eyJhbGc..." --vault ~/my-vault

# 3. Config file
echo "eyJhbGc..." > ~/.vault-health-mcp/license.jwt

Licenses are verified fully offline — no phone-home, no activation server. Get a license: [coming soon — Dodo Payments storefront in verification].

Requirements

Python 3.10+
An Obsidian vault (any size)

License

MIT