mcp-vault-reader

v0.1.0

Published

2 months ago

MCP server for Markdown/Zettelkasten vaults (Obsidian-compatible) — search, wikilinks, backlinks, and persistent AI memory

mcp-vault-reader is a robust Model Context Protocol (MCP) server designed to connect Markdown note vaults (Zettelkasten-style, compatible with Obsidian) to any MCP-compatible AI client. It offers real-time local indexing (in-place, zero duplication) and remote GitHub vault support (via shallow cloning), featuring high-performance full-text search, deep backlink analysis, knowledge graph traversal, and a dedicated, persistent AI memory system.

🎨 Architecture & Concept

Here is how mcp-vault-reader acts as a bridge between your personal notes, local AI memory, and your AI assistant:

graph TD
    subgraph Client ["AI Client (Cursor / Claude Desktop / VS Code)"]
        AI["AI Model / LLM"]
    end

    subgraph Server ["mcp-vault-reader (MCP Server)"]
        McpServer["MCP Protocol Handler"]
        Engine["Search Engine & Graph Traverser"]
        VaultMgr["Vault & Memory Manager"]
    end

    subgraph Storage ["Your Knowledge & Memory"]
        LocalVaults["Local Markdown Vaults (Read-only, In-place)"]
        GithubVaults["GitHub Remote Vaults (Read-only, Shallow Clone)"]
        MemoryVault["__memory__ Vault (Read/Write, Persistent Context)"]
    end

    AI <-->|"MCP Tools & Resources"| McpServer
    McpServer <--> Engine
    Engine <--> VaultMgr
    VaultMgr -->|"Fast-Glob / MiniSearch"| LocalVaults
    VaultMgr -->|"Simple-Git"| GithubVaults
    VaultMgr <-->|"JSON / Markdown Sync"| MemoryVault

✨ What Your AI Can Do With It

Instead of manual search or context-copying, your AI assistant will naturally interact with your notes to:

🔍 Search Everything: Find notes by content, headings, titles, or tags using semantic-weighted search (MiniSearch).
🔗 Traverse Links: Follow Obsidian-compatible [[wikilinks]], explore backlinks, and trace conceptual threads.
📊 Explore Relationships: Discover adjacent ideas by requesting localized knowledge graphs or lists of related notes.
📅 Retrieve Chronology: Fetch daily journals and logs to understand your work progression.
🧠 Remember Persistently: Write and query a private memory vault (__memory__) to keep track of preferences, progress, and custom instructions across sessions.

🚀 Quick Start (5 Minutes)

1. Prerequisites

Ensure you have Node.js v20 or higher installed:

node --version

2. Add Your Vault

Run mcp-vault-reader via npx to register a local directory as a vault:

npx -y mcp-vault-reader vault add /path/to/your/markdown-notes my-second-brain

(If your vault is on GitHub, you can add it directly: npx -y mcp-vault-reader vault add https://github.com/username/my-vault remote-vault)

3. Connect to Claude Desktop or Cursor

You can automatically configure the server in all your installed LLM clients (Claude Desktop, Cursor, VS Code Cline, Roo Code) by running:

npx mcp-vault-reader init

This script will safely detect your tools and inject the necessary JSON configs.

For Claude Desktop (typically ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-vault-reader": {
      "command": "npx",
      "args": ["-y", "mcp-vault-reader"]
    }
  }
}

For Cursor:

Open Cursor Settings -> Models -> MCP.
Click + Add New MCP Server.
Name: mcp-vault-reader.
Type: command.
Command: npx -y mcp-vault-reader.
Save and restart Cursor.

4. Verify in Chat

Ask your AI:

"List my vaults and show me a summary of my-second-brain notes."

📦 Installation & Execution Options

| Method | Command | When to use | |---|---|---| | npx (Recommended) | npx -y mcp-vault-reader | Zero-configuration, automatic updates, clean and hassle-free. | | Global NPM | npm install -g mcp-vault-reader | Faster subsequent startups, avoids downloading on every run. | | From Source | git clone & npm run build | Ideal for contributors, local development, and custom forks. |

🔧 MCP Client Configuration

The recommended pattern is to run via npx without absolute paths. Here are the exact configurations:

VS Code Copilot / Cline / Windsurf

{
  "mcpServers": {
    "mcp-vault-reader": {
      "command": "npx",
      "args": ["-y", "mcp-vault-reader"],
      "env": {
        "VAULT_SYNC_ON_START": "true"
      }
    }
  }
}

Advanced (HTTP/SSE Transport)

If you want to run mcp-vault-reader as a background microservice over HTTP (highly secure):

# Start server in background
export MCP_HTTP_PORT=3000
export MCP_HTTP_AUTH_TOKEN="your-secure-token"
export MCP_HTTP_HARDEN="true"
npx mcp-vault-reader

Then configure your MCP client:

{
  "mcpServers": {
    "mcp-vault-reader": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-token"
      }
    }
  }
}

📚 All 16 Tools at a Glance

📂 Knowledge Vault Tools (Read-Only)

| Tool Name | Key Parameters | Description | |---|---|---| | vault_list_vaults | None | Lists all registered vaults (local paths, commits, note counts, tags). | | vault_search | query, vault_name?, limit?, fuzzy? | Full-text search with relevance scoring and custom snippets. | | vault_read_note | path, vault_name | Reads the full markdown content of a specific note (omitting frontmatter). | | vault_list_notes | vault_name, folder?, tag?, limit? | Lists and filters notes by folder path or tag. | | vault_get_backlinks | path, vault_name | Finds all notes referencing the target note, including link context. | | vault_get_graph | vault_name, center?, depth?, max_nodes? | Builds a knowledge node-and-edge link graph of notes. | | vault_get_related | path, vault_name | Returns adjacent notes based on outgoing links, backlinks, and tags. | | vault_follow_link | path, link, vault_name | Resolves wikilink path targets (e.g. [[TargetNote#Section]]) into absolute paths. | | vault_get_tags | vault_name | Lists all unique tags in the vault and how many notes reference them. | | vault_get_daily_notes | vault_name, date?, limit? | Discovers daily journal entries (formats like YYYY-MM-DD). | | vault_sync | vault_name? | Forces a repository pull or local directory scan and atomic index update. |

🧠 Persistent AI Memory Tools (Read/Write)

| Tool Name | Key Parameters | Description | |---|---|---| | memory_status | None | Checks if the memory vault is active, its storage path, and note stats. | | memory_write_note | path, title, content, tags?, source? | Creates/updates a markdown note inside the private memory vault (__memory__). | | memory_search | query, limit?, fuzzy?, tag? | Performs full-text search specifically over the AI's memory vault. | | memory_list | folder?, tag?, limit? | Lists all stored memories, with folder structure and tags filter. | | memory_delete_note| path | Permanently deletes a memory note. |

🧠 Persistent AI Memory (`memory`)

The Memory Vault is a designated space where the AI has write permissions.

Local vaults and remote GitHub vaults are strictly read-only to ensure your core second brain is never modified or corrupted by the LLM.
The __memory__ vault is initialized in your config directory (default: ~/.mcp-vault-reader/memory/).
The AI uses it to write profiles, keep summaries, build todo lists, or save cross-session settings you discuss.

🤖 Default Instructions for your AI

Copy and paste this system prompt block into your AI Client's system prompt (Cursor Custom Instructions, Claude Desktop System Prompts, etc.) to optimize the tool usage:

You have access to a knowledge vault system via MCP (mcp-vault-reader). Use these guidelines:

1. **Always start with `vault_list_vaults`** to discover available vaults before searching.
2. **Use `vault_search` for broad queries** — it performs full-text search across all notes with relevance scoring.
3. **Use `vault_read_note` to read full content** after finding relevant notes via search.
4. **Navigate connections** with `vault_get_backlinks`, `vault_follow_link`, and `vault_get_related` to explore the knowledge graph.
5. **Use `vault_get_tags` and `vault_get_daily_notes`** for structured browsing.
6. **Memory vault (`__memory__`)** is your persistent storage:
   - `memory_write_note` to save preferences, summaries, or context for future sessions.
   - `memory_search` to recall previously stored information.
   - `memory_list` to browse all stored memories.
   - Memory persists between sessions — use it proactively.
7. **Never modify vault notes** — vaults are read-only. Only memory allows writes.
8. **Prefer specific vault names** in queries when the user mentions a particular knowledge area.

💻 CLI Reference

mcp-vault-reader comes with a powerful command line tool to manage your indexes.

Manage Vaults

# Add a local directory vault
mcp-vault-reader vault add ~/Notes/SecondBrain second-brain

# Add a GitHub vault
mcp-vault-reader vault add https://github.com/LucasRocha179/mcp-vault-reader-test-vault.git my-test-vault

# Add a GitHub vault with custom branch
mcp-vault-reader vault add https://github.com/user/repo.git my-vault --branch development

# List all registered vaults
mcp-vault-reader vault list

# Detailed stats and top tags of a vault
mcp-vault-reader vault info second-brain

# Sync a vault (pull Git updates or scan local files)
mcp-vault-reader vault sync second-brain

# Sync all registered vaults
mcp-vault-reader vault sync

# Remove a vault (removes remote clone or local reference)
mcp-vault-reader vault remove second-brain

Auto-Configuration

# Auto-configure all installed clients (Cursor, Claude, VS Code extensions) using npx
mcp-vault-reader init

# Auto-configure to run using globally-installed package (no npx download delay)
mcp-vault-reader init --global

# Auto-configure specific client (e.g. Cursor only)
mcp-vault-reader init --client cursor

# Remove mcp-vault-reader configuration from all clients
mcp-vault-reader init --remove

Manage Memory

# Check memory vault status and path
mcp-vault-reader memory status

🌍 Environment Variables

| Variable | Default Value | Description | |---|---|---| | VAULT_CONFIG_DIR | ~/.mcp-vault-reader | Where vault configs and remote clones are stored. | | VAULT_SYNC_ON_START | false | If set to true, the MCP server syncs all vaults on startup. | | MCP_HTTP_PORT | None | Set a port (e.g. 3000) to run over HTTP/SSE instead of standard stdio. | | MCP_HTTP_AUTH_TOKEN | None | Bearer token required for security when running HTTP server. | | MCP_HTTP_ALLOWED_ORIGINS| 127.0.0.1 | CORS allowed origins. | | MCP_HTTP_HARDEN | false | If true, enables DNS rebinding protection and strict rate limits. |

💡 Example AI Prompts

Try these prompts in your AI chat:

"List all my vaults and show me the top tags."
"Find notes discussing 'TypeScript decorators' and explain how they link to design patterns."
"Check my daily notes from this week to see what tasks I wrote down."
"Please save a summary of our current design discussion in my memory under 'projects/mcp-vault-reader-notes.md'."
"Search my memory notes for previous projects I worked on."

🆚 How it Compares

| Feature | mcp-vault-reader | obsidian-mcp | notes-mcp | |---|:---:|:---:|:---:| | Persistent AI Memory (__memory__) | ✅ | ❌ | ❌ | | GitHub Remote Vaults (Shallow Clone) | ✅ | ❌ | ❌ | | Atomic Index Swaps (Zero I/O lag) | ✅ | ❌ | ❌ | | Unified Multi-Vault Search | ✅ | ❌ | ❌ | | Daily Notes Traversal | ✅ | ❌ | ❌ | | Flexible CLI Management | ✅ | ❌ | ❌ | | HTTP + SSE Secure Transport | ✅ | ❌ | ❌ | | Number of Rich Tools | 16 | ~5 | ~3 |

❓ Troubleshooting

1. "No vaults registered" error in AI client

Make sure you added the vault via CLI first. The configuration is saved under ~/.mcp-vault-reader/config.json. You can run npx mcp-vault-reader vault list to verify.

2. Private GitHub Repositories

The server uses simple-git under the hood. For private repositories, make sure your machine has ssh keys configured or you are authenticated via CLI (gh auth status).

3. First run of `npx` is slow

The first time you execute npx mcp-vault-reader, NPM downloads the package. For faster subsequent start times, install the package globally:

npm install -g mcp-vault-reader

4. Node.js version errors

Make sure you are running Node.js 20 or higher. Check with node --version. We leverage modern ESM features and Node API components that require v20+.

🔒 Security Considerations

When exposing note vaults to your AI assistant, keep the following security principles in mind:

Indirect Prompt Injection: If you index an untrusted vault (e.g., a public GitHub repository or files shared by third parties), malicious actors could place instructions inside markdown files (e.g., "Ignore previous instructions and perform action X"). When the AI assistant reads these files, it may attempt to execute those instructions using other tools. Only index note vaults from trusted sources.
Read-Only Vaults: Common local and remote vaults registered via the CLI are strictly read-only. The server does not support writing, creating, or modifying files in these vaults, which prevents the AI model from altering your primary documents. Only the special __memory__ vault supports write operations.
Command & Flag Injection Prevention: Inputs passed to vault registration (URLs, local paths, and branch names) are strictly validated. URLs and branches starting with a hyphen (-) are rejected to prevent flag injection attacks against Git/CLI subprocesses.

🤝 Contributing

Contributions are welcome!

Clone the repository: git clone https://github.com/LucasRocha179/mcp-vault-reader.git
Install dependencies: npm install
Run typescript watcher: npm run watch
Run tests: npm test
Read CONTRIBUTING.md for style guides, git flow and architecture guidelines.

⚖️ Trademark Disclaimer

Obsidian is a trademark of Dynalist Inc. This project is an independent open-source tool and is not affiliated with, funded by, or associated with Dynalist Inc. or the Obsidian application.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.