# Mcpvault

> A lightweight Model Context Protocol (MCP) server for safe Obsidian vault access

- **Type:** MCP server
- **Install:** `agentstack add mcp-bitbonsai-mcpvault`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bitbonsai](https://agentstack.voostack.com/s/bitbonsai)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bitbonsai](https://github.com/bitbonsai)
- **Source:** https://github.com/bitbonsai/mcpvault

## Install

```sh
agentstack add mcp-bitbonsai-mcpvault
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCPVault

A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP) standard. Connect any MCP-compatible AI assistant to your knowledge base - works with Claude, ChatGPT, and future AI tools. This server provides safe read/write access to your notes while preventing YAML frontmatter corruption.

  
[https://mcpvault.org](https://mcpvault.org)

[Changelog](./CHANGELOG.md)

[](https://github.com/bitbonsai/mcpvault)
[](https://www.npmjs.com/package/@bitbonsai/mcpvault)
[](https://www.npmjs.com/package/@bitbonsai/mcpvault)
[](https://github.com/sponsors/bitbonsai)
[](https://ko-fi.com/bitbonsai)
[](https://liberapay.com/bitbonsai/)

## Universal Compatibility

Works with any MCP-compatible AI assistant including Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor IDE, Windsurf IDE, Ontheia, and future AI platforms that adopt the MCP standard.

https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c

## Quick Start (5 minutes)

1. **Install Node.js runtime:**

   ```bash
   # Download from https://nodejs.org (v18.0.0 or later)
   # or use a package manager like nvm, brew, apt, etc.
   ```

2. **Test the server:**

   If using the published package:

   ```bash
   npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
   ```

3. **Configure your AI client:**

   **Claude Desktop** - Copy this to `claude_desktop_config.json`:

   ```json
   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
       }
     }
   }
   ```

   **Claude Code** - Copy this to `~/.claude.json`:

   ```json
   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
         "env": {}
       }
     }
   }
   ```

   **OpenCode** - Copy this to `~/.config/opencode/opencode.json`

   ```json
   {
     "mcp": {
       "obsidian": {
         "type": "local",
         "command": [
           "npx",
           "@bitbonsai/mcpvault@latest",
           "/path/to/your/vault/"
         ],
         "enabled": true
       }
     }
   }
   ```

   Replace `/path/to/your/vault` with your actual Obsidian vault path.

   For other platforms, see [detailed configuration guides](#ai-client-configuration) below.

4. **Test with your AI:**
   - "List files in my Obsidian vault"
   - "Read my note called 'project-ideas.md'"
   - "Create a new note with today's date"

**Success indicators:** Your AI should be able to list files and read notes from your vault.

## Why MCPVault?

### Universal AI Compatibility

Built on the open Model Context Protocol standard, MCPVault is not locked to any single AI provider. As more AI assistants adopt MCP, your investment in this tool grows more valuable. Today it works with Claude and ChatGPT - tomorrow it will work with whatever AI tools emerge.

### Future-Proof Your Knowledge Base

Instead of waiting for each AI company to build Obsidian integrations, MCPVault provides a universal adapter that works with any MCP-compatible assistant. One tool, endless possibilities.

### Open Standard, No Lock-in

MCP is an open protocol. You're not tied to any specific vendor or platform. Your notes remain yours, accessible through any compatible AI assistant.

## Features

- ✅ Safe frontmatter parsing and validation using gray-matter with AST-aware updates that preserve raw formatting for unmodified fields
- ✅ Path filtering to exclude `.obsidian` directory and other system files
- ✅ **Complete MCP toolkit**: 14 methods covering all vault operations
  - File operations: `read_note`, `write_note`, `patch_note`, `delete_note`, `move_note`, `move_file`
  - Directory operations: `list_directory`
  - Batch operations: `read_multiple_notes`
  - Search: `search_notes` with multi-word matching and BM25 relevance reranking
  - Metadata: `get_frontmatter`, `update_frontmatter`, `get_notes_info`, `get_vault_stats`
  - Tag management: `manage_tags` (add, remove, list)
- ✅ Write modes: `overwrite`, `append`, `prepend` for flexible content editing
- ✅ Tag management: add, remove, and list tags in notes
- ✅ Safe deletion with confirmation requirement to prevent accidents
- ✅ Automatic path trimming to handle whitespace in inputs
- ✅ TypeScript support with Node.js runtime (using tsx for execution)
- ✅ Comprehensive error handling and validation
- ✅ **Token-optimized responses**: 40-60% smaller responses with minified field names and compact JSON (v0.6.3+)
- ✅ **Optional pretty-printing**: Set `prettyPrint: true` for human-readable debugging
- ✅ **Performance optimized**: No unnecessary token consumption, efficient for large vaults
- ✅ **Zero dependencies**: No Obsidian plugins required, works with any vault structure

## Prerequisites

- [Node.js](https://nodejs.org) runtime (v18.0.0 or later)
- An Obsidian vault (local directory with `.md`, `.markdown`, `.txt`, `.base`, or `.canvas` files)
- MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)

## Installation

### For End Users (Recommended)

No installation needed! Use `npx` to run directly:

```bash
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
```

If you omit the vault path, the server uses your current working directory as the vault root.

### For Developers

1. Clone this repository
2. Use the correct Node.js version:

```bash
nvm use  # Uses Node 24 from .nvmrc
```

3. Install dependencies with npm:

```bash
npm install  # Corepack automatically uses npm 10.9.0
```

4. Test locally with MCP inspector:

```bash
npx @modelcontextprotocol/inspector npm start /path/to/your/vault
```

**Pro tip:** Use MCP Inspector to test all server functionality before configuring with AI clients:

```bash
# Install globally for easier access
npm install -g @modelcontextprotocol/inspector

# Test with any vault
mcp-inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
```

## Usage

### Running the Server

**End users:**

```bash
npx @bitbonsai/mcpvault@latest
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
npx @bitbonsai/mcpvault@latest ./Vault
```

**Developers:**

```bash
npm start
npm start /path/to/your/obsidian/vault
npm start ./Vault
```

### AI Client Configuration

#### Claude Desktop

Add to your Claude Desktop configuration file:

**Single Vault:**

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}
```

**Multiple Vaults:**

```json
{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/PersonalVault"
      ]
    },
    "obsidian-work": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/WorkVault"
      ]
    }
  }
}
```

**Configuration File Locations:**

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

_You can also access this through Claude Desktop → Settings → Developer → Edit Config_

#### ChatGPT Desktop

**Requirements:** ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)

ChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:

1. Access ChatGPT developer mode (beta feature)
2. Configure MCP servers through the built-in MCP client
3. Create custom connectors for your organization

_Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration._

#### Claude Code

Claude Code uses `.claude.json` configuration file:

**User-scoped (recommended):**
Edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}
```

**Project-scoped:**
Edit `.claude.json` in your project or add to the projects section:

```json
{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
        }
      }
    }
  }
}
```

**Using Claude Code CLI:**

```bash
claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault
```

#### Goose Desktop

On Goose Desktop settings, click **Add custom extension**, and on the command field add:

```bash
npx @bitbonsai/mcpvault@latest /path/to/your/vault
```

#### Other MCP-Compatible Clients (2025)

**Confirmed MCP Support:**

- **IntelliJ IDEA 2025.1+** - Native MCP client support
- **Cursor IDE** - Built-in MCP compatibility
- **Windsurf IDE** - Full MCP integration
- **[Ontheia](https://ontheia.ai)** - Self-hosted, open-source AI agent platform
- **Zed, Replit, Codeium, Sourcegraph** - In development
- **Microsoft Copilot Studio** - Native MCP support with one-click server connections

Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.

### Examples

#### Ask your AI assistant about your notes:

- "What files are in my Obsidian vault?"
- "Read my note called 'project-ideas.md'"
- "Show me all notes with 'AI' in the title"

#### Have your AI assistant help with note management:

- "Create a new note called 'meeting-notes.md' with today's date in the frontmatter"
- "Append today's journal entry to my daily note"
- "Prepend an urgent task to my todo list"
- "Add the tags 'project' and 'urgent' to my task note"
- "List all tags in my research note"
- "Remove the 'draft' tag from my completed article"
- "List all markdown files in my 'Projects' folder"
- "Delete the old draft note 'draft-ideas.md' (with confirmation)"

#### Advanced Use Cases:

- **Knowledge Synthesis**: "Summarize all my research notes tagged with 'machine-learning' from the last month"
- **Project Management**: "Update the status in all project notes to 'completed' and add today's date"
- **Content Analysis**: "Find all notes that mention 'API design' and create a comprehensive guide"
- **Smart Tagging**: "Review my untagged notes and suggest appropriate tags based on content"

## Troubleshooting

### Common Issues

#### "command not found: npx"

- **Solution:** Install Node.js runtime from [nodejs.org](https://nodejs.org)
- **Alternative:** Use global install: `npm install -g @bitbonsai/mcpvault`

#### "File not found" when paths look correct

- **Cause:** The server is using the wrong vault root
- **Solution:** Either run the command from your vault directory or pass the vault path explicitly

#### "Permission denied" errors

- **Cause:** Insufficient file system permissions
- **Solution:** Ensure the vault directory is readable/writable by your user

#### "Path traversal not allowed"

- **Cause:** Trying to access files outside the vault
- **Solution:** All file paths must be relative to the vault root

#### AI client not recognizing the server

1. Check the configuration file path is correct for your OS
2. Ensure JSON syntax is valid (use a JSON validator)
3. Restart your AI client after configuration changes
4. Check your AI client's logs for error messages
5. Verify your AI client supports MCP (Model Context Protocol)

#### ".obsidian files still showing up"

- **Expected:** The path filter automatically excludes `.obsidian/**` patterns
- **If still seeing them:** The filter is working as designed for security

### Debug Mode

Run with error logging:

```bash
npx @bitbonsai/mcpvault /path/to/vault 2>debug.log
```

### Getting Help

- [Open an issue](https://github.com/bitbonsai/mcpvault/issues) on GitHub
- Include your OS, Node.js version, and error messages
- Provide the vault directory structure (without sensitive content)

## Testing

Run the test suite:

```bash
npm test
```

## API Methods

### `read_note`

Read a note from the vault with parsed frontmatter.

**Request:**

```json
{
  "name": "read_note",
  "arguments": {
    "path": "project-ideas.md",
    "prettyPrint": false
  }
}
```

**Response (optimized for tokens):**

```json
{
  "fm": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
```

**Response (with prettyPrint: true):**

```json
{
  "fm": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
```

### `write_note`

Write a note to the vault with optional frontmatter and write mode.

**Write Modes:**

- `overwrite` (default): Replace entire file content
- `append`: Add content to the end of existing file
- `prepend`: Add content to the beginning of existing file

**Request (Overwrite):**

```json
{
  "name": "write_note",
  "arguments": {
    "path": "meeting-notes.md",
    "content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
    "frontmatter": {
      "title": "Team Meeting Notes",
      "date": "2023-12-01",
      "tags": ["meetings", "team"]
    },
    "mode": "overwrite"
  }
}
```

**Request (Append):**

```json
{
  "name": "write_note",
  "arguments": {
    "path": "daily-log.md",
    "content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
    "mode": "append"
  }
}
```

**Response:**

```json
{
  "message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
```

### `patch_note`

Efficiently replace an exact string inside an existing note without rewriting the full file.

**Request:**

```json
{
  "name": "patch_note",
  "arguments": {
    "path": "meeting-notes.md",
    "oldString": "- Next milestones",
    "newString": "- Next milestones (owner: Alex)",
    "replaceAll": false
  }
}
```

**Response (success):**

```json
{
  "success": true,
  "path": "meeting-notes.md",
  "message": "Successfully replaced 1 occurrence",
  "matchCount": 1
}
```

**Response (multiple matches with replaceAll=false):**

```json
{
  "success": false,
  "path": "meeting-notes.md",
  "message": "Found 3 occurrences of the string. Use replaceAll=true to replace all occurrences, or provide a more specific string to match exactly one occurrence.",
  "matchCount": 3
}
```

### `list_directory`

List files and directories in the vault.

Note: this includes non-note filenames (for example `pdf`, `png`, `jpg`) so AI assistants can see vault structure, but note tools like `read_note` and `write_note` still operate on note files only (`.md`, `.markdown`, `.txt`, `.base`, `.canvas`).

**Request:**

```json
{
  "name": "list_directory",
  "arguments": {
    "path": "Projects",
    "prettyPrint": false
  }
}
```

**Response (optimized):**

```json
{
  "dirs": ["AI-Tools", "Web-Development"],
  "files": ["project-template.md", "roadmap.md"]
}
```

### `delete_note`

Delete a note from the vault (requires confirmation for safety).

**Request:**

```json
{
  "name": "delete_note",
  "arguments": {
    "path": "old-draft.md",
    "confirmPath": "old-draft.md",
    "trashMode": "local"
  }
}
```

**Response (Success):**

```json
{
  "success": true,
  "path": "old-draft.md",
  "message": "Successfully moved note to vault trash: old-draft.md"
}
```

**Trash modes:**
- `none` (default): permanent delete
- `local`: move to `.trash` inside the vault, preserving folder structure
- `system`: move to the OS trash/re

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bitbonsai](https://github.com/bitbonsai)
- **Source:** [bitbonsai/mcpvault](https://github.com/bitbonsai/mcpvault)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bitbonsai-mcpvault
- Seller: https://agentstack.voostack.com/s/bitbonsai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.