Core features

MCPVault works directly with vault files. These tools and path checks define what clients can do with them.

Full-text search

Search matches note filenames and content, supports multiple words, and ranks results with BM25.

[
  {
    "p": "Notes/GTD.md",
    "t": "GTD",
    "ex": "...getting things done...",
    "mc": 5,
    "ln": 12
  },
  {
    "p": "Books/Deep Work.md",
    "t": "Deep Work",
    "ex": "...focus and productivity...",
    "mc": 8,
    "ln": 45
  }
]

Frontmatter updates

AST-aware YAML updates preserve raw formatting for unmodified fields. Dates, quotes, and time values keep their original form while only changed keys are rewritten.

Note and file operations

Tools read, write, patch, move, list, and delete notes. Patch updates replace exact text instead of rewriting full files.

Vault boundary

Path checks block traversal, symlink escapes, dotfiles, .obsidian, .git, and node_modules.

Runs on Node.js

MCP clients launch the server as a local Node.js process over stdio.

Compact responses

Search and batch responses use short field names by default. prettyPrint returns expanded output when needed.

TypeScript API

The package exports TypeScript declarations and public types for library use.

MIT licensed

Source code, tests, and issue tracking are public on GitHub.

18 MCP tools

Tools cover note reads and writes, exact patches, file moves, search, tags, frontmatter, outlines, line ranges, and vault statistics.

MCP client support

Setup guides cover Claude Desktop, ChatGPT+ Desktop, Claude Code, OpenCode, Gemini CLI, OpenAI Codex, Cursor, Windsurf, and IntelliJ.

Compare access methods

The main difference is where each approach runs and which layer controls access to vault files.

Feature

MCPVault

This package

Plugin + REST API

Obsidian community plugin

General file access

Client or shell tools

Setup

One command

Run npx with the vault path

Plugin setup

Install and configure a REST API plugin

Client-specific

Configure filesystem access in each client

Obsidian running

Not required

Reads vault files directly

Required

The plugin runs inside Obsidian

Not required

Reads files outside Obsidian

Plugin dependency

None

Runs as a separate local process

Required

Uses a community REST API plugin

None

Uses client or shell file tools

Frontmatter updates

AST-aware

Preserves formatting for unchanged YAML fields

Endpoint-specific

Behavior depends on the plugin endpoint

Tool-specific

Behavior depends on the file editing tool

Built in

Filename and content search with BM25 ranking

Obsidian-backed

Uses search exposed by the plugin

Tool-specific

May use grep, indexing, or client search

Connection

Local stdio

The MCP client launches the server

Local HTTP

The plugin exposes an API port

Local process

The client reads files directly

Move operations

Built in

Note and file moves use vault path checks

Plugin endpoint

Behavior follows the plugin implementation

Tool-specific

Behavior depends on the file editing tool

Access boundary

Vault-scoped

Blocks traversal, symlink escapes, and restricted paths

API-scoped

Access follows plugin and Obsidian settings

Client-scoped

Access follows the client's filesystem permissions

Installation Source code

FAQ

Setup, file access, and recovery.

Does my data leave my computer?

MCPVault reads and writes files on your machine and has no hosted service. Your AI client or provider may receive note content used in requests.

Does Obsidian need to be running?

No. MCPVault uses filesystem access, so Obsidian can be closed.

Can I use multiple vaults?

Yes. Configure one MCP server entry for each vault path.

What file types are supported?

Read and write tools support .md, .markdown, .txt, .base, and .canvas files. list_directory may show other filenames, but note tools do not read those files as notes.

Is search semantic?

Search uses lexical matching with BM25 ranking, not embeddings or a vector index. For semantic search, pair MCPVault with a separate vector-search MCP server such as Qdrant's mcp-server-qdrant or Chroma's chroma-mcp.

What if the AI makes a mistake?

Use backups or version control for recovery. Deletions require path confirmation, and file operations are restricted to the configured vault.