🧠 Obsidian MCP Server

Turn your Obsidian vaults into structured context sources for Claude Desktop

📚 Technical Deep Dive: Read the full development journey — research notes, design decisions, and iteration history.

---

Why This Exists

Obsidian Vaults are where my knowledge lives. But connecting them to LLMs requires more than just "read file" — you need vault-aware sessions, heading-based navigation, and token-efficient search that doesn't blow your context window.

This MCP server solves that by treating Obsidian vaults as first-class data sources for LLMs, with tools designed around how markdown actually works (structure-based, not line-number-based).

---

✨ Key Features

🗂️ Multi-Vault Session Management

• Configure multiple vaults in vaults.yaml (personal, work, research, etc.)
• Switch active vault mid-conversation: "Use my work vault"
• Session-aware context tracking across tool calls

🎯 Structure-Aware Editing

Traditional file operations use line numbers. Markdown uses headings.

## Project Ideas
Some content here

### Idea 1
Details about idea 1

## Resources
Links and references

With this server:

• insert_after_heading("Project Ideas") → Adds content in the right semantic location
• replace_section("Idea 1") → Updates just that subsection
• delete_section("Resources") → Removes heading + all content until next same-level heading

🔍 Token-Efficient Search

Searching 10 notes with full content: ~50,000 tokens 💸
Searching with contextual snippets: ~1,500 tokens ✅

# Returns 3 snippets per match, ~200 chars each
search_obsidian_content("MCP server design patterns")

Claude gets enough context to understand matches without burning your token budget.

🏷️ Frontmatter Control

• Read, merge, replace, or remove YAML frontmatter without touching the note body
• Enforces schema validation (size limits, UTF-8, YAML-safe types)
• Designed for future automations like tag management and template validation

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Claude Desktop
• One or more Obsidian vaults

Installation

# Clone the repository
git clone https://github.com/nbaradar/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies with uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

Configuration

1. Create vaults.yaml in the project root:

default: personal
vaults:
  personal:
    path: "/Users/you/Documents/PersonalVault"
    description: "Primary personal vault"
  
  work:
    path: "/Users/you/Documents/WorkVault"
    description: "Work projects and documentation"

2. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "/absolute/path/to/obsidian-mcp-server/server.py"
      ]
    }
  }
}

3. Restart Claude Desktop

You should see "🔌 MCP" in Claude Desktop with your Obsidian tools available.

---

🎬 What It Looks Like

Once configured, you'll see your Obsidian tools available in Claude Desktop:

22 tools available for multi-vault note management with heading-aware operations

Additionally, you can use your preferred MCP Clients as well! Here I'm using VSCode with Copilot in Agent mode.
For more detail on how to connect VSCode to MCP, check here

You can even use it with your own Local LLM models! Here I'm running qwen3-14b using LM Studio

---

📖 Usage Examples

Basic Operations

User: "Create a note called 'Project Ideas' in my personal vault"
Claude: [uses create_obsidian_note]

User: "Switch to my work vault and list all notes"
Claude: [uses set_active_vault, then list_obsidian_notes]

User: "Search for notes about 'machine learning'"
Claude: [uses search_obsidian_content for snippets]

Advanced: Structured Editing

User: "In my 'Meeting Notes' file, add today's standup under the 'Daily Standups' heading"
Claude: [uses insert_after_heading_obsidian_note]

User: "Replace the 'Action Items' section with..."
Claude: [uses replace_section_obsidian_note]

User: "Add a summary paragraph at the end of 'Project Updates' before any subsections"
Claude: [uses append_to_section_obsidian_note]

User: "What’s the most recent note in my Mental Health folder?"
Claude: [uses list_notes_in_folder("Mental Health", include_metadata=True, sort_by="modified")]

---

🛠️ Available Tools

Management

Tool	Purpose
list_vaults	Discover configured vaults and current session state
set_active_vault	Switch active vault for subsequent operations

Core Operations

Tool	Purpose
create_obsidian_note	Create new markdown file
retrieve_obsidian_note	Read full note contents
replace_obsidian_note	Overwrite entire file
append_to_obsidian_note	Add content to end
prepend_to_obsidian_note	Add content to beginning
delete_obsidian_note	Remove file
move_obsidian_note	Move or rename note (optional backlink updates)

Structured Editing

Tool	Purpose
insert_after_heading_obsidian_note	Insert content below a heading
append_to_section_obsidian_note	Append content to a heading’s section before subsections
replace_section_obsidian_note	Replace content under a heading
delete_section_obsidian_note	Remove heading and its section

Frontmatter

Tool	Purpose
read_obsidian_frontmatter	Return only the YAML frontmatter block
update_obsidian_frontmatter	Merge fields into existing frontmatter
replace_obsidian_frontmatter	Overwrite the entire frontmatter block
delete_obsidian_frontmatter	Remove the frontmatter block entirely

Discovery

Tool	Purpose
list_obsidian_notes	List all notes, optionally include metadata
search_obsidian_notes	Search note titles (supports metadata + sorting)
list_notes_in_folder	Targeted folder listing (metadata + recursion support)
search_obsidian_content	Token-efficient content search
search_notes_by_tag	Token-efficient tag-based search

Metadata on demand: list_obsidian_notes, search_obsidian_notes, and list_notes_in_folder accept include_metadata=True to attach ISO timestamps and file sizes. The flag adds roughly 9 tokens per note, so keep it off for broad listings and enable it when you need “most recent” or “largest note” style queries.

---

🧭 Internal Architecture

As of v1.4.3, the codebase uses a modular package structure for better maintainability and testability:

obsidian_vault/
├── core/                    # Pure business logic (NO MCP dependencies)
│   ├── vault_operations.py       # Path validation and sandboxing
│   ├── note_operations.py        # Note CRUD operations
│   ├── search_operations.py      # Search and discovery
│   ├── section_operations.py     # Heading-based manipulation
│   └── frontmatter_operations.py # YAML frontmatter ops
│
├── tools/                   # MCP tool wrappers (thin layer)
│   ├── vault_tools.py       # Vault management tools
│   ├── note_tools.py        # Note CRUD tool wrappers
│   ├── search_tools.py      # Search tool wrappers
│   ├── section_tools.py     # Section tool wrappers
│   └── frontmatter_tools.py # Frontmatter tool wrappers
│
├── server.py                # FastMCP server initialization
├── config.py                # Configuration loading (vaults.yaml)
├── session.py               # Per-session active vault tracking
└── models.py                # Data models (VaultMetadata, etc.)

Key Benefits:

• Separation of Concerns: Core logic is MCP-agnostic and can be tested independently
• Single Responsibility: Each module has one clear purpose
• Extensibility: Add new features by extending core modules, tool wrappers auto-register
• Testability: Core modules can be unit tested without MCP server infrastructure

Data Flow:

1. MCP tool wrapper receives request (handles context, vault resolution)
2. Calls corresponding core operation (pure business logic)
3. Core operation returns structured data
4. Tool wrapper formats response for MCP client

---

🏗️ Design Principles

1. Token Efficiency First

Every tool is designed to minimize context window usage:

• Snippet-based search over full-content retrieval
• Heading-based navigation over full-file reads
• Combined operations over multiple tool calls

Task	Naive	This Server	Savings
“Find most recent note in Mental Health”	~60k tokens	~450 tokens	~99%
“Find largest files”	~30k tokens	~850 tokens	~97%

2. Markdown-Native Operations

Traditional editors use line numbers. This breaks with note edits. Semantic anchors (headings) remain stable as content changes.

3. Session-Aware Context

Claude can switch between vaults mid-conversation without losing state.

4. MCP Builder Compliance

All tools follow the MCP Builder Skill format — one-line summary → explanation → parameters → return schema → use/don’t-use guidance.

5. Logging and Debugging

The server uses Python’s logging (stderr/file) for all operations: vault switches, CRUD events, helper calls, and errors.

• Logs stored in ~/Library/Logs/Claude/ when running under Claude Desktop.
• Avoid print() — it breaks STDIO JSON-RPC streams.
• Token cost tracking hooks (coming soon) will log per-operation token estimates for debugging.

6. Error Handling Philosophy

Graceful, descriptive, and safe:

• Missing notes / bad paths → suggests correct tools or paths.
• Malformed YAML → reports exact line/type.
• Vault or filesystem errors → cites config path.
• Destructive operations always confirmed by clients.

---

🧪 Testing Summary

Implementation verified across multiple real vaults and automated suites.

• 27 tag-search tests covering format handling, case insensitivity, metadata sorting, nested folders, AND/OR semantics, performance, and async MCP integration.
• 4 path-normalization regression tests ensuring dotted note titles, nested paths, uppercase .MD, and traversal rejection behave as expected.
• Test command: PYTHONPATH=. uv run --with pytest --with pytest-asyncio pytest tests/test_path_normalization.py tests/test_tag_search.py

---

🌿 Frontmatter Rules

Frontmatter tools operate purely on YAML blocks to save tokens and avoid unnecessary content rewrites.

• Validates UTF-8 and YAML-safe types; rejects malformed or oversized metadata.
• Merge semantics by default (preserve unknown keys).
• Designed for future tag automation and template validation.

---

🔌 Remote Access (Planned)

Currently runs via STDIO (local-only). Future versions will support HTTP transport for remote clients with optional authentication per the MCP specification.

---

🚧 Known Limitations

• No regex or property/frontmatter-based search (yet).
• No SQLite indexing or caching.
• No image/attachment management.
• No backlink maintenance (beyond link updates on move/rename).
• No HTTP transport or auth (STDIO only).
• Note titles with dots are fully supported as of v1.4.2; _normalize_note_identifier preserves inner segments while enforcing sandbox rules.

---

🗺️ Roadmap

• [x] v1.0 — Core CRUD operations
• [x] v1.1 — Token-efficient content search
• [x] v1.2 — Structured heading-based editing
• [x] v1.3 — Improve Vault Navigation
• [x] v1.4 — Frontmatter Manipulation + Tag Search
• [x] v1.4.1 — Tag search tooling refinement (completed)
• [x] v1.4.2 — Preserve dotted note identifiers in _normalize_note_identifier
• [x] v1.4.3 — Refactor Codebase Structure
• [x] v1.5 — Pydantic Data Models for Input Validation
• [ ] v1.6 — Vault-Aware Prompt Resources
• [ ] v1.6.1 — Vault-Specific Templates
• [ ] v2.0 — HTTP transport for remote access

See AGENTS.md for detailed development notes and architecture decisions.

---

📚 Documentation

• Development Journey — Full technical writeup with research notes, debugging stories, and design iterations
• MCP Overview — My research notes on the Model Context Protocol
• Building Your First MCP Server — Step-by-step guide

---

🤝 Contributing

This project is in active development. Contributions, issues, and feature requests are welcome!

Particularly interested in:

• Testing on Windows/Linux (currently Mac-focused)
• Additional vault sources (Notion, Roam, etc.)
• Performance optimization for large vaults (10k+ notes)

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

Built with:

• FastMCP by Anthropic
• Model Context Protocol specification
• Inspiration from the Obsidian community's API work

---

<p align="center"> <i>Built because context matters, and Obsidian is where mine lives.</i> </p>