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.

Support

If obsidian-mcp-sb saves you time, consider sponsoring me on GitHub or buy me a coffee.

License

MIT