mcp-vault-reader

<p align="center"> <img src="https://raw.githubusercontent.com/LucasRocha179/mcp-vault-reader/main/assets/banner.jpg" alt="mcp-vault-reader" width="800"> </p>

<p align="center"> <a href="https://npmjs.com/package/mcp-vault-reader"><img src="https://img.shields.io/npm/v/mcp-vault-reader" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/npm/l/mcp-vault-reader" alt="license"></a> <img src="https://img.shields.io/node/v/mcp-vault-reader" alt="node version"> <img src="https://img.shields.io/npm/dw/mcp-vault-reader" alt="downloads/week"> <a href="https://github.com/LucasRocha179/mcp-vault-reader/actions"><img src="https://img.shields.io/github/actions/workflow/status/LucasRocha179/mcp-vault-reader/ci.yml" alt="CI"></a> </p>

---

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.

<details> <summary><b>Or Configure Manually</b></summary>

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

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

For Cursor:

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

</details>

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:

1. 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.
2. 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.
3. 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!

1. Clone the repository: git clone https://github.com/LucasRocha179/mcp-vault-reader.git
2. Install dependencies: npm install
3. Run typescript watcher: npm run watch
4. Run tests: npm test
5. 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.