Obsidian MCP Server

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

• 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
• 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

Option 1: Environment Variable (Recommended)

Windows (PowerShell):

# Set vault path (replace with your vault location)
$env:OBSIDIAN_VAULT_PATH = "C:\Users\YourName\Documents\ObsidianVault"

# Test server
node dist\index.js

macOS/Linux (Bash):

# Set vault path (replace with your vault location)
export OBSIDIAN_VAULT_PATH="/Users/YourName/Documents/ObsidianVault"

# Test server
node dist/index.js

Option 2: Configuration File

Create config.json in the project root:

{
  "includePatterns": ["**/*.md"],
  "excludePatterns": [".obsidian/**", ".trash/**", "node_modules/**"],
  "enableWrite": true,
  "vectorSearch": {
    "enabled": true,
    "provider": "transformers",
    "model": "Xenova/all-MiniLM-L6-v2",
    "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/all-MiniLM-L6-v2) works well for most users. Consider upgrading based on your hardware:

• High-end CPU (Ryzen 9+, i9+, M3 Max+): Use Xenova/bge-base-en-v1.5 for best quality
• Mid-range CPU (Ryzen 5-7, i5-i7, M2): Use Xenova/bge-small-en-v1.5 for improved quality
• 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": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\YourName\\Documents\\ObsidianVault"
      }
    }
  }
}

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": {