CoMfUcIoS/obsidian-mcp-sb

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 for vault structure, CLI arguments, and configuration examples.

See 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 for more example queries.

Documentation

See 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 for common issues and solutions.

See for details on search weights and scoring.

See for details on security features and protections.

See for development workflow and storage details.

See 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 for the architecture diagram. See 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 for a full list of production and development dependencies.

License

MIT