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
pip install vault-health-mcp
Usage
Claude Code
claude mcp add vault-health -- vault-health-mcp --vault ~/my-vault
Claude Desktop
{
"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:
# 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