Skip to main content
Glama
vault-mcp
by Lincyaw

vault-mcp

Markdown + SQLite knowledge store with bidirectional [[wikilinks]], exposed as an MCP server. Designed for AI agents to maintain an interconnected knowledge base.

Installation

uvx vault-mcp                           # run directly without install
pip install vault-mcp                   # core (keyword search only)
pip install "vault-mcp[semantic]"       # + embedding-based semantic search

Related MCP server: LLM Wiki MCP

Running the MCP Server

# Start with default settings (vault in ./vault)
vault-mcp

# Custom vault directory
VAULT_DIR=/path/to/notes vault-mcp

# With semantic search enabled
VAULT_DIR=./vault VAULT_EMBEDDING_MODEL=jinaai/jina-embeddings-v5-text-nano vault-mcp

Environment Variables

Variable

Default

Description

VAULT_DIR

./vault

Root directory for markdown files

VAULT_EMBEDDING_MODEL

(none)

Sentence-transformers model name. Enables semantic search when set

Client Configuration

Claude Code

claude mcp add vault -- vault-mcp

Or .mcp.json:

{
  "mcpServers": {
    "vault": {
      "type": "stdio",
      "command": "vault-mcp",
      "env": { "VAULT_DIR": "./vault" }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Add to your MCP settings:

{
  "vault": {
    "command": "vault-mcp",
    "env": { "VAULT_DIR": "./vault" }
  }
}

Python Library (no MCP)

from vault_mcp import MarkdownVault, create_vault_tools

vault = MarkdownVault("./my-vault")
vault.write("skill/debugging", {"type": "skill", "confidence": "pattern"}, "# Debugging\n\n...")

# Or get all 11 tools as a dict of callables
tools = create_vault_tools(vault)
result = tools["vault_search"](query="debugging", mode="keyword")

Note Format

Each note is a .md file with YAML frontmatter, organized in type-based folders:

vault/
  skill/
    timeout-diagnosis.md
  concept/
    connection-pooling.md
  episodic/
    2024-01-15-incident.md
---
type: skill
tags: [database, timeout]
confidence: pattern
status: active
---

# Timeout Diagnosis

Description of the skill...

## Evidence
- [[episodic/2024-01-15-incident]]: First observed during outage

## Related
- [[concept/connection-pooling]]

Frontmatter Fields

Field

Required

Values

type

Yes

skill, episodic, concept, failure-pattern, system-knowledge

confidence

Yes

fact, pattern, heuristic

tags

No

Free-form string list

status

Auto

active, superseded, archived

Tools

Write & Edit

Tool

Description

vault_write(path, frontmatter, body)

Create or overwrite a note

vault_write_batch(entries)

Write multiple notes atomically

vault_edit(path, operation, params)

Incremental edit (4 operations below)

vault_delete(path)

Delete a note

vault_rename(old_path, new_path)

Rename + auto-rewrite all backlinks

Edit Operations

Operation

Params

Use

replace_string

{"old": "...", "new": "..."}

Inline corrections

set_frontmatter

{"confidence": "fact"}

Update metadata

replace_section

{"heading": "## Evidence", "body": "..."}

Rewrite a section

append_section

{"heading": "## Evidence", "content": "..."}

Append to a section

Read & Browse

Tool

Description

vault_read(path)

Read frontmatter + body

vault_list(path, depth, type_filter)

Browse directory

Search & Discovery

Tool

Description

vault_search(query, filters, mode, limit)

FTS5 / semantic / hybrid search

vault_backlinks(path)

Who links to this note

vault_traverse(start, depth, direction)

BFS graph traversal with directed edges

vault_lint()

Find dead links + orphan notes

Validation

Every write/edit automatically checks and returns warnings:

  • Required frontmatter fields (type, confidence)

  • Valid enum values

  • H1 heading present in body

  • All [[wikilinks]] resolve to existing notes

The write succeeds regardless — warnings are informational for the agent to decide whether to fix.

Architecture

.md files (source of truth, git-trackable)
    │
    ▼
.vault.db (SQLite index, auto-rebuilt if deleted)
    ├── notes       — YAML frontmatter metadata
    ├── notes_fts   — FTS5 full-text search
    ├── links       — [[wikilink]] directed graph
    ├── tags        — tag index
    └── notes_vec   — embedding vectors (optional)

License

MIT

Available Tools

11 tools
vault_deleteA

Delete a note and remove it from all indexes.

Args: path: Note path to delete.

Inputs: path (required). Returns: result

vault_editA

Apply an incremental edit to an existing note without rewriting the full content.

Args: path: Note path to edit. operation: One of "replace_string", "set_frontmatter", "replace_section", "append_section". params: Operation-specific parameters: - replace_string: {"old": "...", "new": "..."} - set_frontmatter: {"field": "value", ...} (merge update) - replace_section: {"heading": "## Section", "body": "new content"} - append_section: {"heading": "## Section", "content": "appended text"}

Returns warnings if the edit introduces structural issues.

Inputs: path (required), params (required), operation (required). Returns: result

vault_lintA

Check vault health: find dead [[wikilinks]] and orphan notes with no connections.

Inputs: no named parameters. Returns: result

vault_listA

Browse notes under a path.

Args: path: Directory path (e.g. "skill"). Use "" for vault root. depth: How many levels deep to list (default 1). type_filter: Only return notes of this type (e.g. "skill", "concept").

Inputs: path (required), depth, type_filter. Returns: result

vault_readA

Read a note from the vault. Returns its frontmatter and body.

Args: path: Note path (e.g. "concept/connection-pooling")

Inputs: path (required). Returns: result

vault_renameA

Rename or move a note. All [[backlinks]] in other notes are rewritten automatically.

Args: old_path: Current note path. new_path: New note path.

Inputs: new_path (required), old_path (required). Returns: result

vault_traverseA

Explore the link graph around a note via BFS traversal.

Args: start: Starting note path. depth: How many hops to follow (default 2). direction: "forward" (outgoing links), "backward" (incoming), or "both".

Returns nodes with depth and directed edges (source → target).

Inputs: start (required), depth, direction. Returns: result

vault_writeA

Create or overwrite a note in the vault.

Args: path: Note path relative to vault root (e.g. "skill/timeout-diagnosis") frontmatter: YAML metadata dict. Required fields: type, confidence. body: Markdown body content. Should start with "# Title".

Returns warnings if the note has structural issues.

Inputs: body (required), path (required), frontmatter (required). Returns: result

vault_write_batchA

Write multiple notes atomically in a single transaction.

Args: entries: List of dicts, each with "path", "frontmatter", "body" keys.

All notes are written together — if one fails, none are committed.

Inputs: entries (required). 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 11 tools

    Disambiguation4/5

    Tools are mostly distinct with clear purposes, but vault_backlinks and vault_traverse (backward direction) both return incoming links, which could cause misselection. However, descriptions clarify the difference: backlinks is a direct lookup, while traverse explores the graph with depth.

    Naming Consistency4/5

    All tools share the vault_ prefix, and most follow a verb pattern (write, read, edit, delete, list, search, lint, traverse). However, vault_backlinks and vault_write_batch deviate from the verb-only convention, making the set slightly inconsistent.

    Tool Count5/5

    11 tools cover a complete note management workflow: CRUD, batch, search, list, lint, and graph exploration. The number is well-scoped, neither overwhelming nor thin.

    Completeness5/5

    The tool set provides full coverage of the vault lifecycle: create, read, update, delete, rename, batch operations, search, and health/link analysis. There are no obvious dead ends or missing core operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Local-first knowledge base MCP server. Lets AI agents (Claude Code, Cursor, etc.) read and write your personal knowledge base through 20 MCP tools. Zero cloud dependency — all files stay on your machine.
      707
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for persistent, compounding markdown wikis maintained by LLMs. Enables incremental knowledge base building with interlinked pages, search, and raw source management.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a local, domain-agnostic knowledge base using Markdown notes with frontmatter. Enables AI agents to capture, read, search, link, and maintain notes with atomic writes and privacy controls.
      13
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with a local, private Markdown-based memory vault and SQLite search. Enables agents to search, read, list, and traverse linked knowledge pages via MCP with zero external runtime dependencies.
      7
      33 PyPI
      9
      MIT