WRITINGGagandeep Bhatia
Chat with GaganChatPortfolio
Sign in with GoogleSign in with Google. Opens in new tab
‹ Index10 min left
10 min read

Build an MCP Server That Connects Claude Directly to Your Obsidian Vault

How to build a lightweight MCP server that gives Claude direct access to your Obsidian vault, with project-level scoping, BM25 search, and 16 tools for reading, writing, and managing notes.

@gagandeep023/mcpvaultVIEW ON NPMVIEW ON GITHUB

Copy-pasting notes into AI chats is tedious. Every time you want Claude to help with something from your Obsidian vault, you have to manually find the note, copy it, paste it into the chat, and repeat. For a tool that's supposed to save time, that's a lot of friction.

MCPVault is an MCP server that gives Claude direct access to your vault. No more copy-paste. Claude just knows your notes.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external tools and data sources. Think of it like USB for AI. Instead of each AI company building custom integrations, MCP provides a universal protocol that any AI client can use.

Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise), Cursor, Windsurf, and more already support it.

What Does This Server Do?

It's a lightweight Node.js server that sits between your AI assistant and your Obsidian vault. It exposes 16 tools that let the AI read, write, search, and manage your notes.

Here's what you can do:

  • Read and write notes with full YAML frontmatter support
  • Search across your entire vault with BM25 relevance ranking
  • Patch notes without rewriting the whole file
  • Manage tags, move files, batch read, get vault stats
  • Project scoping to isolate notes per project

The server works directly with markdown files on disk. No Obsidian plugins required. Obsidian doesn't even need to be running.

The Key Feature: Project Isolation

Here's the thing most Obsidian MCP servers miss. If you work on multiple projects, you don't want your AI mixing contexts.

When debugging a production issue in a work repo, you don't want Claude pulling up notes from a side project. And when brainstorming ideas for a personal app, work deployment docs shouldn't be leaking in.

MCPVault solves this with project-level scoping using a simple --project flag.

How It Works

Organize your vault into project folders:

text
obsidian-vault/
  work/
    api-notes.md
    deployment.md
  side-project/
    ideas.md
    architecture.md

Then scope the server to one project:

bash
mcpvault --project work ~/Documents/obsidian-vault

When scoped, all operations are restricted to that folder. Notes from other projects are completely invisible. Claude can only see and touch what's relevant.

Automatic Scoping per Project Directory

The real power comes when you pair this with Claude Code's project-level config. Each project directory can have its own MCP server configuration pointing to the right vault subfolder.

Open Claude Code in a work repo, and it automatically connects to work notes. Switch to a side project, and it connects to those notes instead. Zero manual switching.

Quick Setup (5 Minutes)

1. Install

bash
npm install -g @gagandeep023/mcpvault

2. Create Your Vault

If you don't have Obsidian yet:

bash
# macOS
brew install --cask obsidian

# Create a vault folder
mkdir -p ~/Documents/obsidian-vault

3. Connect to Claude Code

bash
claude mcp add obsidian-vault --scope user -- mcpvault ~/Documents/obsidian-vault

That's it. Restart Claude Code and start talking to your notes.

4. Try It Out

Once connected, just talk naturally:

  • "What notes do I have about API design?"
  • "Create a meeting note for today with an agenda section"
  • "Search my vault for anything about deployment"
  • "Add the tag 'urgent' to my todo list"
  • "Summarize all my notes tagged with 'architecture'"

Claude picks the right tool automatically. You never have to think about which MCP method to call.

Why Not Just Use an Existing Solution?

There are several Obsidian MCP servers out there. Here's how they compare:

  • mcp-obsidian (3k stars): Requires the Local REST API plugin and Obsidian running. More moving parts.
  • smithery mcp-obsidian (1.4k stars): Read and search only. No write capabilities.
  • obsidian-mcp-tools (659 stars): Great semantic search, but needs multiple Obsidian plugins installed.

MCPVault takes a different approach: zero dependencies on Obsidian plugins, full read/write support, and project isolation out of the box.

What's Under the Hood

The server is built with TypeScript and the official MCP SDK. Here's the architecture:

Claude Code <--stdio--> MCPVault Server <--filesystem--> Obsidian Vault
MCPVault Architecture

Key technical details:

  • Zero runtime dependencies beyond the MCP SDK and gray-matter (for YAML parsing)
  • BM25 search ranking for relevant results, not just keyword matching
  • Token-optimized responses with minified field names (40-60% smaller payloads)
  • Path traversal protection so the AI can never escape your vault directory
  • Safe deletion requiring explicit path confirmation to prevent accidents
  • 156 tests covering filesystem operations, search, frontmatter parsing, path filtering, and URI generation

The 16 Tools

  • read_note - Read a note with parsed frontmatter
  • write_note - Write, append, or prepend to a note
  • patch_note - Find and replace text in a note
  • delete_note - Delete with confirmation
  • move_note - Move or rename a note
  • move_file - Move any file (binary-safe)
  • list_directory - List files and folders
  • read_multiple_notes - Batch read up to 10 notes
  • search_notes - Full-text search with BM25
  • get_frontmatter - Extract frontmatter only
  • update_frontmatter - Update metadata without changing content
  • get_notes_info - File metadata for multiple notes
  • get_vault_stats - Vault-level statistics
  • manage_tags - Add, remove, or list tags
  • list_projects - Show available project folders
  • get_current_project - Check which project is active

Auto Setup with Claude Agent

Want a Claude agent to set up everything for you? Paste this prompt into Claude Code:

text
Install @gagandeep023/mcpvault globally, then read the guide and follow it
step by step to set up the Obsidian vault and MCP server for my projects:

npm install -g @gagandeep023/mcpvault
cat $(npm root -g)/@gagandeep023/mcpvault/guide.md

The included guide walks through every step: installing Obsidian, creating the vault, setting up project folders, registering the MCP server, and verifying it works.

What's Next

Some features on the roadmap:

  • Semantic search using embeddings for meaning-based queries instead of just keywords
  • Wikilink resolution so the AI can follow [[links]] between notes
  • Template support for creating notes from predefined structures
  • Sync status to show which notes have been modified since last AI interaction

Try It Out

Install in 30 seconds:

bash
npm install -g @gagandeep023/mcpvault
claude mcp add obsidian-vault --scope user -- mcpvault ~/Documents/obsidian-vault
  • GitHub: github.com/Gagandeep023/mcpvault - Star the repo if you find it useful!
  • npm: npmjs.com/package/@gagandeep023/mcpvault

If you try it out, drop a comment, open an issue on GitHub, or give the repo a star. It helps others discover it.

Spotted a typo or have a thought on this post?