Obsidian MCP Server

Provides real-time Claude AI access to Obsidian vaults via Model Context Protocol (MCP)

Overview

This MCP server enables Claude to query, search, and read notes from Obsidian vaults without token limitations. Unlike Claude Projects which load all documents into context, this server provides dynamic, on-demand access to your knowledge base.

Features

• Multi-Vault Support: Serve multiple Obsidian vaults from a single MCP server instance (v2.0)

• Real-time Vault Access: Query and read notes dynamically without pre-uploading

• Automatic Index Updates: File system watcher automatically updates vector index when notes change (v1.3.0)

• Vector Search: Semantic search using local embeddings (Transformers.js) or Anthropic API

• Hybrid Search: Combines keyword and semantic search for optimal results

• Write Operations: Create, update, and delete notes programmatically

• Cross-Vault Search: Search across all configured vaults with vault: "*"

• Search Tools: Keyword, tag, and folder-based filtering

• Multiple Formats: JSON and Markdown response formats

• Secure: Path validation and security checks prevent unauthorized access

• Token Efficient: No vault size limitations or token constraints

Quick Start

Prerequisites

• Node.js 18+ (recommended: 20+)

• TypeScript 5.7+

• Obsidian vault with markdown notes

• Claude Desktop or MCP-compatible client

Installation

Windows (PowerShell):

# 1. Clone or navigate to repository
cd /path/to/obsidian-mcp-server

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Verify build succeeded
Test-Path dist\index.js  # Should return True

macOS/Linux (Bash):

# 1. Clone or navigate to repository
cd ~/obsidian-mcp-server

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Verify build succeeded
ls dist/index.js  # Should exist

Configuration

Create config.json in the project root with your vault(s):

{
  "vaults": [
    {
      "name": "work",
      "path": "C:\\Users\\YourName\\Documents\\WorkVault",
      "enableWrite": true
    },
    {
      "name": "personal",
      "path": "C:\\Users\\YourName\\Documents\\PersonalVault",
      "enableWrite": false
    }
  ],
  "vectorSearch": {
    "enabled": true,
    "provider": "transformers",
    "model": "Xenova/bge-small-en-v1.5",
    "indexOnStartup": "auto"
  },
  "searchOptions": {
    "maxResults": 20,
    "excerptLength": 200,
    "caseSensitive": false,
    "includeMetadata": true
  },
  "logging": {
    "level": "info",
    "file": "logs/mcp-server.log"
  }
}

Choosing the Right Embedding Model:

The default model (Xenova/bge-small-en-v1.5) offers excellent quality at 384 dimensions. Consider alternatives based on your needs:

• Default: Xenova/bge-small-en-v1.5 — best quality-to-resource ratio, recommended for multi-vault setups

• High-end CPU (Ryzen 9+, i9+, M3 Max+): Use Xenova/bge-base-en-v1.5 for best quality (768 dims, ~2x RAM)

• Multilingual vault: Use Xenova/paraphrase-multilingual-MiniLM-L12-v2

See Semantic Search Guide for detailed model comparison.

Initial Indexing (Required for Large Vaults)

Important: For vaults with 1,000+ notes or when switching embedding models, run initial indexing standalone before using Claude Desktop.

Quick Start:

# Windows
$env:OBSIDIAN_VAULT_PATH = "X:\Path\To\Your\Vault"
$env:OBSIDIAN_CONFIG_PATH = "D:\repos\obsidian-mcp-server\config.json"
node --expose-gc --max-old-space-size=16384 dist\index.js

# macOS/Linux
export OBSIDIAN_VAULT_PATH="/path/to/vault"
export OBSIDIAN_CONFIG_PATH="$HOME/obsidian-mcp-server/config.json"
node --expose-gc --max-old-space-size=16384 dist/index.js

After indexing completes, configure Claude Desktop (see below) for daily usage.

📚 See Indexing Workflow Guide for detailed instructions, troubleshooting, and model switching procedures.

Claude Desktop Integration

Windows

Edit Claude Desktop configuration:

# Config location: %APPDATA%\Claude\claude_desktop_config.json
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add this configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "--expose-gc",
        "--max-old-space-size=16384",
        "/path/to/obsidian-mcp-server/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_CONFIG_PATH": "/path/to/obsidian-mcp-server/config.json"
      }
    }
  }
}

macOS

Edit Claude Desktop configuration:

# Config location: ~/Library/Application Support/Claude/claude_desktop_config.json
vi ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "--expose-gc",
        "--max-old-space-size=16384",
        "/path/to/obsidian-mcp/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_CONFIG_PATH": "/path/to/obsidian-mcp-server/config.json"
      }
    }
  }
}

Multi-Vault Setup

The server natively supports multiple vaults via the vaults array in config.json. All vaults are served by a single MCP server process — no need for separate server entries per vault.

Each vault gets its own independent vector index (stored in each vault's .mcp-vector-store/ folder) and file watcher. Use the vault parameter on all tools to target a specific vault, or "*" on read tools to search across all vaults.

{
  "vaults": [
    {
      "name": "work",
      "path": "C:\\Users\\YourName\\Documents\\WorkVault",
      "enableWrite": true
    },
    {
      "name": "personal",
      "path": "C:\\Users\\YourName\\Documents\\PersonalVault",
      "enableWrite": false
    }
  ],
  "vectorSearch": {
    "enabled": true,
    "provider": "transformers",
    "model": "Xenova/bge-small-en-v1.5",
    "indexOnStartup": "auto"
  }
}

Memory planning: Each vault loads the embedding model independently (~150-300MB RAM per vault depending on model). Plan memory accordingly.

Legacy Note: If you previously used OBSIDIAN_VAULT_PATH with one server process per vault, the server auto-migrates this to a single-vault vaults array at startup. The old multi-process approach still works but is no longer recommended.

Restart Claude Desktop

After configuration, completely quit and restart Claude Desktop for changes to take effect.

Documentation

• Indexing Workflow Guide - Initial setup, model switching, and troubleshooting

• Configuration Guide - Complete configuration reference

• Semantic Search Guide - Semantic search setup and usage

Usage

In Claude Conversations

Once configured, Claude can automatically access your vault:

User: "Search my vault for notes about Python debugging"

Claude will use: obsidian_search_vault(query="Python debugging")
Returns: Matching notes with excerpts and URIs

User: "Show me the full Getting-Started note"

Claude will read: obsidian://vault/Guides/Getting-Started.md
Returns: Complete note content

Available Tools

All tools require a vault parameter specifying which vault to operate on. Use the vault name from your config.json. Read tools also accept "*" for cross-vault search.

obsidian_list_vaults

List all configured vaults with their status and metadata.

Parameters: None required.

Returns: Vault names, paths, write status, and index health (note count, model, indexed date).

obsidian_search_vault

Search vault by keywords, tags, or folders.

Parameters:

• vault (required): Vault name or "*" for all vaults

• query (required): Search keywords (space-separated)

• tags (optional): Filter by tags (must have ALL)

• folders (optional): Limit to specific folders

• limit (optional): Max results (1-100, default: 20)

• offset (optional): Pagination offset (default: 0)

• response_format (optional): "markdown" or "json" (default: "markdown")

Examples:

// Search a specific vault
obsidian_search_vault((vault = "work"), (query = "JavaScript testing"));

// Search across all vaults
obsidian_search_vault((vault = "*"), (query = "project"), (tags = ["active"]));

obsidian_semantic_search

Search vault using semantic similarity (meaning-based) instead of keyword matching.

Parameters:

• vault (required): Vault name or "*" for all vaults

• query (required): Natural language query (1-500 chars)

• limit (optional): Max results (1-50, default: 10)

• min_score (optional): Similarity threshold (0-1, default: 0.5)

• hybrid (optional): Combine with keyword search (default: false)

• response_format (optional): "markdown" or "json" (default: "markdown")

Examples:

// Semantic search in one vault
obsidian_semantic_search((vault = "work"), (query = "machine learning ethics"));

// Cross-vault hybrid search
obsidian_semantic_search(
  (vault = "*"),
  (query = "web development best practices"),
  (hybrid = true)
);

obsidian_read_note

Read the full content of a specific note with parsed frontmatter. Read-only operation.

Parameters:

• vault (required): Vault name (no "*")

• path (required): Relative path to note (e.g., "Projects/MyNote.md")

• response_format (optional): "markdown" or "json" (default: "markdown")

obsidian_create_note

Create a new note in a specific vault. Write must be enabled for the target vault.

Parameters:

• vault (required): Vault name (no "*")

• path (required): Relative path for new note (e.g., "Projects/NewNote.md")

• content (required): Note content (markdown)

• frontmatter (optional): YAML frontmatter object

obsidian_update_note

Update an existing note's content or frontmatter.

Parameters:

• vault (required): Vault name (no "*")

• path (required): Relative path to note

• content (optional): New content (replaces existing)

• frontmatter (optional): New frontmatter (merges with existing)

• append (optional): Append content instead of replace (default: false)

obsidian_delete_note

Delete a note from a specific vault. Write must be enabled for the target vault.

Parameters:

• vault (required): Vault name (no "*")

• path (required): Relative path to note

• confirm (required): Must be true to confirm deletion

Available Resources

Every note in your vault is exposed as a resource with URI:

obsidian://vault/{vaultName}/[relative-path]

Claude can list all available notes and read specific notes by URI.

Architecture

Design Philosophy

This server uses a search-tool-only approach rather than pre-registering thousands of individual resources:

• Efficient: Claude uses obsidian_search_vault to find notes dynamically

• Scalable: Works with vaults of any size (tested with 5,000+ notes)

• Fast: No startup delay from resource registration

• MCP-compliant: Follows best practices for large datasets

Claude discovers notes through search, receives obsidian://vault/ URIs, and can then read specific notes on demand.

Component Diagram

graph LR
    A[Claude AI] -->|MCP Protocol| B[MCP Server]
    B -->|stdio| A
    B --> C[Vault Registry]
    C --> D1[Vault: work]
    C --> D2[Vault: personal]
    D1 --> E1[Search Engine]
    D1 --> F1[Vector Store]
    D1 --> G1[File Watcher]
    D2 --> E2[Search Engine]
    D2 --> F2[Vector Store]
    D2 --> G2[File Watcher]

Components

• index.ts - Server initialization, multi-vault setup, and transport

• obsidian-server.ts - MCP request handlers (resources, tools) with vault routing

• vault-registry.ts - Multi-vault context management and resolution

• search.ts - Search engine with scoring and filtering

• embeddings.ts - Vector store and embedding generation

• utils.ts - Configuration, file operations, security

Security

Path Validation

All file paths are validated to prevent directory traversal attacks:

// Checks that requested path is within vault boundaries
if (!isPathSafe(notePath, vaultPath)) {
  throw new Error("Access denied: path outside vault");
}

Read-Only Mode

By default, server is read-only. To enable write operations (future feature):

{
  "enableWrite": true
}

Input Sanitization

• Zod schemas validate all tool inputs

• Path normalization prevents Windows/Unix path issues

• Query limits prevent resource exhaustion (max 500 chars)

Development

Build

npm run build

Development Mode (Hot Reload)

npm run dev

Linting

npm run lint
npm run format

Testing

npm test

Troubleshooting

Server Not Starting

Check vault path:

# Windows
Test-Path "C:\Users\YourName\Documents\ObsidianVault"  # Should return True

# macOS/Linux
ls -la ~/Documents/ObsidianVault  # Should show folder contents

Check build output:

# Windows
Test-Path .\dist\index.js  # Should return True

# macOS/Linux
ls dist/index.js  # Should exist

View error logs:

# All platforms
node dist/index.js

Claude Not Finding Server

1. Verify config file location:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Check JSON syntax: Use a JSON validator

3. Restart Claude Desktop completely (don't just close window)

4. Check Claude logs:

   • Windows: %APPDATA%\Claude\logs\

   • macOS: ~/Library/Logs/Claude/

Search Returns No Results

• Check exclude patterns - Your notes might be excluded

• Verify file extension - Only .md files are indexed

• Check query terms - Try broader terms

Permission Errors

Ensure your user has read access to:

• Vault directory

• All subdirectories

• All .md files

Configuration Options

Full configuration schema:

{
  vaults: Array<{                   // Vault definitions (required)
    name: string;                   // Unique vault identifier
    path: string;                   // Absolute path to vault
    enableWrite?: boolean;          // Per-vault write override
    includePatterns?: string[];     // Per-vault include override
    excludePatterns?: string[];     // Per-vault exclude override
    vectorSearch?: { ... };         // Per-vault vector config override
  }>;
  includePatterns: string[];        // Default glob patterns to include
  excludePatterns: string[];        // Default glob patterns to exclude
  enableWrite: boolean;             // Default write permission (default: false)
  vectorSearch?: {                  // Default vector search config
    enabled: boolean;               // Enable semantic search
    provider: "transformers";       // Embedding provider
    model?: string;                 // Model name (default: Xenova/bge-small-en-v1.5)
    indexOnStartup: "auto" | "always" | "never" | boolean;
  };
  searchOptions: {
    maxResults: number;             // Max search results (default: 20)
    excerptLength: number;          // Excerpt length (default: 200)
    caseSensitive: boolean;         // Case-sensitive search (default: false)
    includeMetadata: boolean;       // Include frontmatter (default: true)
  };
  logging: {
    level: string;                  // Log level (default: "info")
    file: string;                   // Log file path
  };
}

Performance

Optimization Strategies

• Lazy loading - Only reads files when requested

• Pagination - Limits search results

• Character limits - Truncates large responses

• Exclude patterns - Skips unnecessary files

Recommended Limits

• Vault size: < 10,000 notes

• Search results: < 100 per query

• File size: < 10MB per note

Future Enhancements

• Indexing - Pre-build search index for faster queries

• Caching - Cache frontmatter and metadata

• Vector search - Semantic similarity search

• Watch mode - Real-time file system monitoring

MCP Protocol Compliance

This server follows MCP best practices:

• ✅ Zod input validation

• ✅ Tool annotations (readOnlyHint, destructiveHint, etc.)

• ✅ Multiple response formats (JSON/Markdown)

• ✅ Character limits (25k) with truncation

• ✅ Proper error handling

• ✅ Pagination support

• ✅ Security validation

• ✅ Descriptive tool documentation

• ✅ Search-tool pattern for large datasets

Changelog

v2.0.0 (January 2025) - Multi-Vault Support

New Features:

• ✅ Multi-vault support: Serve multiple Obsidian vaults from a single MCP server instance

• ✅ obsidian_list_vaults tool: List all configured vaults with index health and metadata

• ✅ vault parameter: All tools require a vault parameter for explicit targeting

• ✅ Cross-vault search: Use vault: "*" on read tools to search across all vaults

• ✅ Per-vault config: Override write permissions, include/exclude patterns, and vector search settings per vault

• ✅ Per-vault file watchers: Independent file watching and auto-indexing per vault

• ✅ Updated URI scheme: obsidian://vault/{vaultName}/{path} includes vault context

Configuration:

• ✅ vaults array: Define multiple vaults in config.json

• ✅ Legacy migration: OBSIDIAN_VAULT_PATH env var auto-migrates to single-vault vaults array

• ✅ Per-vault overrides: enableWrite, includePatterns, excludePatterns, vectorSearch inherit from server defaults

Breaking Changes:

• ⚠️ vault parameter required: All tools now require a vault parameter

• ⚠️ URI scheme changed: URIs now include vault name: obsidian://vault/{vaultName}/{path}

• ⚠️ Config format: vaults array is the recommended config format (legacy auto-migration preserves backward compatibility)

Migration:

• Existing configs with OBSIDIAN_VAULT_PATH continue to work via auto-migration

• Update tool calls to include vault parameter

• Update any URI parsing to handle the new {vaultName} segment

v1.4.0 (December 2025) - Parallel Batch Processing & Smart Auto-Indexing

Performance Improvements:

• 🚀 10x faster indexing: Parallel batch processing with Promise.all (10 concurrent embeddings)

• ⚡ 65x speedup: 5,681 notes indexed in 5.5 minutes (down from 6+ hours)

• 💾 Robust checkpoints: Proper Vectra transaction management (beginUpdate/endUpdate)

• 🔧 Memory optimized: Explicit GC at checkpoints, pipeline refresh every 500 notes

• 📊 Production tested: Successfully indexed 5,681/6,056 notes (93.8% coverage)

New Features:

• ✅ Smart indexOnStartup modes: "auto" (smart detection), "always", "never"

• ✅ Automatic model change detection: No manual config toggling when switching models

• ✅ Index validation: Detects missing, corrupted, or incompatible indexes

• ✅ Model metadata storage: Stores model info in index for validation

• ✅ Seamless model switching: Just change model in config and restart - auto re-indexes

Bug Fixes:

• ✅ Fixed checkpoint persistence: Vectra index now properly flushed to disk at checkpoints

• ✅ Eliminated index loss: Transaction management prevents progress loss on crashes

• ✅ Type safety: Fixed batch processing parameter types for NoteMetadata

Breaking Changes:

• ⚠️ indexOnStartup enhanced: Now accepts string values ("auto", "always", "never") in addition to boolean (backwards compatible)

• ⚠️ Default changed: indexOnStartup now defaults to "auto" instead of false

Migration:

• Old config with true/false still works (mapped to "always"/"never")

• Recommended: Update to "auto" for best experience

• Delete old indexes: If you have incomplete indexes from v1.3, delete .mcp-vector-store/ and let v1.4 rebuild with parallel processing

v1.3.0 (October 2025) - Automatic Index Updates

New Features:

• ✅ Automatic file watching: Real-time vector index updates when notes change (chokidar)

• ✅ Debounced re-indexing: Smart 2-second delay prevents excessive rebuilds

• ✅ Seamless integration: No manual re-indexing required

Breaking Changes:

• ⚠️ Config property renamed: autoIndex → indexOnStartup (better reflects that it only controls initial indexing on server startup, not the automatic file watching)

v1.2.0 (October 2025) - Vector Search & Write Operations

New Features:

• ✅ Semantic search with vector embeddings (Transformers.js)

• ✅ Write operations: Create, update, and delete notes

• ✅ Hybrid search: Combine semantic and keyword search (60/40 weighting)

• ✅ Incremental indexing: Track file modifications for efficient updates

• ✅ Local embeddings: Privacy-first with local Transformers.js models

Bug Fixes:

• ✅ Fixed config.json loading to use script directory instead of CWD

• ✅ Fixed tags handling for non-array frontmatter tags

• ✅ Improved error handling for malformed YAML frontmatter

Performance:

• ✅ Tested with 5,457 note vault (5,456 indexed successfully)

• ✅ Fast startup with optional auto-indexing

• ✅ Vectra-based local vector store (no external server required)

v1.0.0 (January 2025) - Production Release

Architecture:

• ✅ Search-tool-only design (no resource pre-registration)

• ✅ Fast startup (< 1 second)

• ✅ Scalable to vaults of any size

Security:

• ✅ Updated all dependencies (0 vulnerabilities)

• ✅ ESLint 9.17.0, Rimraf 6.0.1, TypeScript-ESLint 8.18.2

• ✅ Eliminated deprecated packages with memory leak risks

MCP SDK:

• ✅ Migrated to MCP SDK 1.20+ API

• ✅ Updated from old registerResourceList/registerResource methods

• ✅ Clean TypeScript compilation (0 errors)

Testing:

• ✅ Verified with 5,453 note vault

• ✅ Tested on Windows 11 with Node.js 25.0.0

• ✅ Confirmed Claude Desktop integration

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Follow existing code style

2. Add tests for new features

3. Update documentation

4. Follow MCP best practices

References

• MCP Specification

• MCP TypeScript SDK

• Claude MCP Documentation

• Obsidian API

Built with ❤️ for the Obsidian + Claude community