markdown-vault-mcp

Python MCP server for programmatic access to markdown-based knowledge vaults

A sister project to mdvault, providing AI assistants with seamless access to your markdown vault through the Model Context Protocol.

Overview

While mdvault provides a Rust CLI and TUI for human interaction with your vault (templates, captures, macros, validation), markdown-vault-mcp exposes your vault to AI assistants through MCP. Together, they form a complete toolkit for managing markdown-based knowledge systems.

flowchart TB
    A[AI Assistant<br/>Claude, etc.] -->|MCP| B[markdown-vault-mcp<br/>Python/FastMCP]
    B --> C[Markdown Vault<br/>.md files]
    B -.->|future| D[mdvault<br/>Rust CLI]
    D -.-> C

Related MCP server: brain-mcp

Features

• Browse: List notes and folders in your vault

• Read: Access note content and YAML frontmatter metadata

• Search: Find notes by content with contextual results

• Update: Modify frontmatter, append content, toggle tasks

• Navigate: Explore backlinks, outgoing links, orphans, and related notes

• Context: Get activity summaries for days, weeks, and notes

• Focus: Set and track active project context

• Tasks & Projects: Create tasks, projects, and meetings with auto-generated IDs

• Reports: Generate activity reports and daily dashboards

Installation

Requires Python 3.13+ and uv.

git clone https://github.com/agustinvalencia/markdown-vault-mcp.git
cd markdown-vault-mcp
uv sync

Configuration

The server needs the MARKDOWN_VAULT_PATH environment variable pointing to your vault root.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "markdown-vault": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/markdown-vault-mcp",
        "run", "mcp-start"
      ],
      "env": {
        "MARKDOWN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Restart Claude Desktop to activate.

Claude Code

Add as a user-scoped MCP server (available in all projects):

claude mcp add markdown-vault \
  -s user \
  -e MARKDOWN_VAULT_PATH=/path/to/your/vault \
  -- uv --directory /path/to/markdown-vault-mcp run mcp-start

This writes to ~/.claude.json. To scope it to a single project instead, use -s project (writes to .mcp.json in the project root).

Restart the Claude Code session (or use /mcp to reload) to activate.

Verifying the connection

Claude Desktop: Open a new conversation and check the MCP icon shows markdown-vault as connected.

Claude Code: Run claude mcp list and confirm markdown-vault shows ✓ Connected.

Available Tools

42 tools organized into 10 categories:

See docs/tools.md for detailed documentation of each tool.

Usage Examples

Once configured, your AI assistant can interact with your vault:

"What notes do I have about Python?"

I'll search your vault for Python-related notes.

Found 5 notes mentioning Python:
- concepts/python.md
- projects/learning-plan.md
- daily/2024-01-15.md
...

"Show me what links to my programming concepts note"

Looking for backlinks to concepts/programming.md...

3 notes link to this:
- concepts/python.md
- concepts/rust.md
- projects/learning-plan.md

"Mark the 'Review PR' task as complete in today's daily note"

Updated daily/2024-01-20.md:
- [x] Review PR comments

Development

# Install dependencies
uv sync

# Run the server (for testing)
MARKDOWN_VAULT_PATH=/path/to/vault uv run python -m mdvault_mcp_server

# Run with debug logging
MARKDOWN_VAULT_MCP_DEBUG=true uv run python -m mdvault_mcp_server

# Lint
uv run ruff check src/

# Format
uv run ruff format src/

Relationship with mdvault

Compatibility: Requires mdvault v0.3.5+

The MCP server delegates complex operations (tasks, projects, meetings, captures, macros) to the mdvault CLI, ensuring consistent behavior between human and AI interactions.

License

MIT License - see LICENSE for details.