markdown-vault-mcp

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

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:

| Category | Key Tools | |----------|-----------| | List | list_notes, list_folders | | Read | read_note, read_note_excerpt, get_metadata | | Search | search_notes, search_notes_with_context | | Update | update_metadata, append_to_note, update_task_status, capture_content | | Daily | add_to_daily_note, log_to_daily_note | | Zettelkasten | find_backlinks, find_outgoing_links, find_orphan_notes, suggest_related_notes | | Context | get_active_context, get_context_day, get_context_week, get_context_note, get_context_focus | | Tasks & Projects | create_task, create_project, create_meeting, complete_task, archive_project, list_tasks, list_projects | | Macros | run_macro | | Management | get_daily_dashboard, get_activity_report, validate_vault, rename_note |

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+

| Feature | mdvault (Rust) | markdown-vault-mcp (Python) | |---------|----------------|----------------------------| | Purpose | Human CLI/TUI interaction | AI assistant integration | | Tasks/Projects | Yes | Yes (via mdvault CLI) | | Meetings | Yes (v0.3.0+) | Yes (via mdvault CLI) | | Templates | Yes | Yes (via mdvault CLI) | | Captures | Yes (Lua) | Yes (via mdvault CLI) | | Macros | Yes (Lua) | Yes (via mdvault CLI) | | Focus Mode | Yes | Yes (via mdvault CLI) | | Context Queries | Yes | Yes (via mdvault CLI) | | Activity Reports | Yes | Yes (via mdvault CLI) | | Reading | Via CLI commands | MCP tools + CLI | | Search | SQLite index | Direct file search | | Link Graph | SQLite index | Real-time parsing | | Validation | Type schemas | Yes (via mdvault CLI) |

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.