Skip to main content
Glama

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

Related MCP server: obsidian-markdown-lint-mcp-server

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

Available Tools

6 tools
check_vault_healthA
Read-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_orphansA
Read-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_statisticsA
Read-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

    A4.1/5.0

    Scored across 6 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    All tools use snake_case with verb_noun pattern except vault_statistics (noun_noun). Consistent style, but one minor deviation.

    Tool Count5/5

    6 tools is well-scoped for a vault health MCP: configuration, comprehensive check, repair, statistics, and specific queries. No excess or deficiency.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers