English Français العربية

io.github.onetrueclaude-creator/vault-health-mcp

Official registry Health

Obsidian vault structural health: broken links, orphans, missing frontmatter, safe auto-repair.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package vault-health-mcp
Claude Code 
claude mcp add vault-health-mcp -e 'VAULT_HEALTH_LICENSE=<your vault_health_license>' -- uvx vault-health-mcp==0.2.0 --vault
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "vault-health-mcp": {
            "command": "uvx",
            "args": [
                "vault-health-mcp==0.2.0",
                "--vault"
            ],
            "env": {
                "VAULT_HEALTH_LICENSE": "<your vault_health_license>"
            }
        }
    }
}

Environment variables

  • VAULT_HEALTH_LICENSE secret Pro license JWT (optional). Unlocks the repair_vault auto-fix tool. See the README for details.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. vault-health-mcp
  2. Install
  3. Usage
  4. MCP Tools
  5. How auto-repair works (Pro)
  6. Pro tier
  7. Requirements
  8. License

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

ToolTierDescription
configure_vaultFreePoint the server at a vault at runtime
check_vault_healthFreeFull structural scan: broken links, orphans, missing frontmatter
find_orphansFreeList all structurally disconnected leaf notes
find_broken_linksFreeList all wikilinks pointing to non-existent files
vault_statisticsFreeFile count, link count, orphan %, frontmatter coverage
repair_vaultProAuto-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

Frequently asked questions

What is io.github.onetrueclaude-creator/vault-health-mcp?

Obsidian vault structural health: broken links, orphans, missing frontmatter, safe auto-repair.

How do I install io.github.onetrueclaude-creator/vault-health-mcp?

It runs on your machine. In Claude Code: claude mcp add vault-health-mcp -e 'VAULT_HEALTH_LICENSE=<your vault_health_license>' -- uvx vault-health-mcp==0.2.0 --vault. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.onetrueclaude-creator/vault-health-mcp need an API key?

Yes. It expects VAULT_HEALTH_LICENSE, which you set in its configuration.

Is io.github.onetrueclaude-creator/vault-health-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.onetrueclaude-creator/vault-health-mcp?

It is published by onetrueclaude-creator. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.