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: ```mermaid 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: ```bash node --version ``` ### 2. Add Your Vault Run `mcp-vault-reader` via `npx` to register a local directory as a vault: ```bash 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: ```bash 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`): ```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 ```json { "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): ```bash # 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: ```json { "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: ```markdown 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash 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](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](LICENSE) file for details.