Obsidian MCP Second Brain Server

A read-only MCP server for intelligent, secure access to your Obsidian vault—enabling semantic search, metadata filtering, and more for LLMs.

Features

• Efficient Database Storage: SQLite-based indexing for large vaults with persistent caching
• Memory Mode Option: Optional in-memory indexing for small vaults or development
• Semantic Search: Full-text search across all notes with fuzzy matching
• Tag-Based Filtering: Search by hierarchical tags (e.g., work/puppet, tech/golang)
• Path-Based Filtering: Filter by directory patterns (e.g., Work/Puppet/**)
• Temporal Queries: Filter notes by creation/modification dates
• Metadata Filtering: Filter by type, status, and category
• Note Retrieval: Get full content of specific notes
• Smart Summarization: Generate summaries of note collections
• Recent Notes: Quick access to recently modified notes
• Archive Control: Optionally include archived notes in searches
• Security: Path traversal protection, file size limits, input validation

Read-Only Design

This MCP server is intentionally read-only to ensure your vault remains safe during AI interactions. It provides:

• ✅ Search and retrieve notes
• ✅ Filter by metadata and paths
• ✅ Generate summaries and statistics
• ❌ No note creation or editing
• ❌ No file modifications

For write operations, consider using dedicated Obsidian plugins with built-in safety checks.

Installation

Configuration & Installation

One-Click Installation

• VS Code:
• VS Code Insiders:
• Cursor:

Manual Installation

No installation needed! Use directly with npx:

npx -y @comfucios/obsidian-mcp-sb --vault-path "/path/to/your/vault"

Local Development

cd obsidian-mcp-sb
npm install
npm run build
npm link

This makes the server available globally as obsidian-mcp-sb.

Claude Code & Claude Desktop

Claude Code

Add the server using:

claude mcp add obsidian-sb -- npx -y @comfucios/obsidian-mcp-sb --vault-path "/path/to/your/vault"

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-sb": {
      "command": "npx",
      "args": [
        "-y",
        "@comfucios/obsidian-mcp-sb",
        "--vault-path",
        "/path/to/your/vault"
      ]
    }
  }
}

See docs/configuration.md for vault structure, CLI arguments, and configuration examples.

See docs/api.md for the full MCP API reference and usage examples.

Usage with Claude Code

Add to your MCP configuration file.

Single Vault Configuration

macOS/Linux: Edit ~/Library/Application Support/Claude/claude_desktop_config.json Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-sb": {
      "command": "npx",
      "args": [
        "-y",
        "@comfucios/obsidian-mcp-sb",
        "--vault-path",
        "/Users/ioanniskarasavvaidis/Documents/Obsidian Vault"
      ]
    }
  }
}

Multiple Vault Configuration

You can configure multiple vault instances:

{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": [
        "-y",
        "@comfucios/obsidian-mcp-sb",
        "--vault-path",
        "/Users/username/Documents/Personal Vault"
      ]
    },
    "obsidian-work": {
      "command": "npx",
      "args": [
        "-y",
        "@comfucios/obsidian-mcp-sb",
        "--vault-path",
        "/Users/username/Documents/Work Vault"
      ]
    }
  }
}

Local Development Setup

If you're developing locally with npm link:

{
  "mcpServers": {
    "obsidian-sb": {
      "command": "obsidian-mcp-sb",
      "args": ["--vault-path", "/path/to/your/vault"]
    }
  }
}

See docs/examples.md for more example queries.

Documentation

See docs/README.md for:

• API Reference
• Configuration & CLI Options
• Example Queries
• Development & Storage Architecture
• Contributing
• Dependencies
• Architecture & Database Schema
• Security & Search
• Example Queries
• Development
• Contributing
• Dependencies
• License

Quick Start

Run the server instantly with npx (no install required):

npx -y @comfucios/obsidian-mcp-sb --vault-path "/path/to/your/vault"

Or add to Claude Code/Claude Desktop (see Configuration & Installation below).

Troubleshooting & FAQ

See docs/configuration.md for common issues and solutions.

See docs/search.md for details on search weights and scoring.

See docs/security.md for details on security features and protections.

See docs/development.md for development workflow and storage details.

See docs/contributing.md for contribution guidelines.

Storage Architecture

The server uses SQLite database storage by default for efficient indexing and persistent caching:

• Database Mode (Default): Stores indexed notes in .obsidian-mcp/notes.db within your vault

  • Persistent indexing (survives server restarts)
  • Efficient for large vaults (1000+ notes)
  • Full-text search with SQLite FTS5
  • Lower memory usage

• Memory Mode (Optional): Use --use-memory flag for in-memory storage

  • Faster for small vaults (<100 notes)
  • No disk I/O overhead
  • Useful for development and testing
  • Uses Fuse.js for fuzzy search

See docs/architecture.md for the architecture diagram. See docs/database-schema.md for the database schema.

Architecture

• src/index.ts: MCP server implementation with tool handlers
• src/vault.ts: Vault indexing orchestration and security controls
• src/storage.ts: Storage interface abstraction
• src/database-storage.ts: SQLite-based storage implementation
• src/memory-storage.ts: In-memory storage implementation with Fuse.js
• src/storage-factory.ts: Storage factory pattern for mode selection
• src/config.ts: Configuration management with defaults
• src/types.ts: TypeScript type definitions and validation utilities
• src/__tests__/: Unit tests for critical functionality

See docs/dependencies.md for a full list of production and development dependencies.

License

MIT