Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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 -.-> CFeatures
- 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 syncConfiguration
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-startThis 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 commentsDevelopment
# 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.