vault-health-mcp
Allows checking and repairing Obsidian vault structural health, including broken wikilinks, orphaned notes, and missing frontmatter.
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., "@vault-health-mcp check my vault for broken links and orphans"
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.
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-mcpRelated MCP server: obsidian-markdown-lint-mcp-server
Usage
Claude Code
claude mcp add vault-health -- vault-health-mcp --vault ~/my-vaultClaude Desktop
{
"mcpServers": {
"vault-health": {
"command": "uvx",
"args": ["vault-health-mcp", "--vault", "/path/to/vault"]
}
}
}MCP Tools
Tool | Tier | Description |
| Free | Point the server at a vault at runtime |
| Free | Full structural scan: broken links, orphans, missing frontmatter |
| Free | List all structurally disconnected leaf notes |
| Free | List all wikilinks pointing to non-existent files |
| Free | File count, link count, orphan %, frontmatter coverage |
| 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.jwtLicenses 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
Available Tools
6 toolscheck_vault_healthARead-only
Scan the vault for structural issues: broken wikilinks, orphaned notes, missing frontmatter. Returns a categorized list of all issues found.
Inputs: no named parameters. Returns: result
configure_vaultA
Configure the vault path for this server. Call this first if the server started without a --vault argument.
Inputs: vault_path (required). Returns: result
find_broken_linksARead-only
Find all broken wikilinks — [[targets]] that don't resolve to any file in the vault. Excludes wikilinks inside code spans.
Inputs: no named parameters. Returns: result
find_orphansARead-only
Find all orphaned leaf notes — notes typed as 'leaf' in frontmatter that are not linked from any hub or branch file.
Inputs: no named parameters. Returns: result
repair_vaultA
[Pro] Auto-repair safe structural issues. Only adds content (frontmatter, plain text replacements for broken links). Never deletes files or content. Requires Pro license.
Inputs: fix_frontmatter, fix_broken_links. Returns: result
vault_statisticsARead-only
Vault-level analytics: file count, link count, orphans, broken links, frontmatter coverage percentage.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools are mostly distinct, but find_orphans and find_broken_links overlap with check_vault_health which also finds these issues. This could cause confusion about which tool to use.
All tools use snake_case with verb_noun pattern except vault_statistics (noun_noun). Consistent style, but one minor deviation.
6 tools is well-scoped for a vault health MCP: configuration, comprehensive check, repair, statistics, and specific queries. No excess or deficiency.
Core operations (configure, check, repair, statistics) are covered. Minor gap: no tool to individually fix a specific broken link without Pro license, but repair_vault handles auto-fix.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Audit your MCP servers for poisoned tools and leaked secrets, and check AI-generated code for flaws.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.
Related MCP Servers
- AlicenseAqualityBmaintenanceThe most feature-complete MCP server for Obsidian vaults. 23 tools and 3 resources for search, read, write, tags, link analysis, graph traversal, and canvas support.41121 npm34MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lints, validates, and renders your Obsidian vault markdown — all inside Docker.3MIT
- AlicenseBqualityDmaintenanceA lightweight MCP server for intelligent, non-invasive analysis of Obsidian vaults.4MIT
- FlicenseCqualityDmaintenanceMCP server to query and modify an Obsidian vault or any folder of markdown files. It provides search, tag filtering, backlinks, and CRUD operations on notes, with path traversal protection.11-