Provides read-only access to Obsidian vaults with semantic search, tag-based filtering, path-based filtering, temporal queries, metadata filtering, note retrieval, and smart summarization capabilities
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:
Local Development
This makes the server available globally as obsidian-mcp-sb
.
Claude Code & Claude Desktop
Claude Code
Add the server using:
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
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
Multiple Vault Configuration
You can configure multiple vault instances:
Local Development Setup
If you're developing locally with npm link
:
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
Quick Start
Run the server instantly with npx (no install required):
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 vaultPersistent 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 storageFaster 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 handlerssrc/vault.ts
: Vault indexing orchestration and security controlssrc/storage.ts
: Storage interface abstractionsrc/database-storage.ts
: SQLite-based storage implementationsrc/memory-storage.ts
: In-memory storage implementation with Fuse.jssrc/storage-factory.ts
: Storage factory pattern for mode selectionsrc/config.ts
: Configuration management with defaultssrc/types.ts
: TypeScript type definitions and validation utilitiessrc/__tests__/
: Unit tests for critical functionality
See docs/dependencies.md for a full list of production and development dependencies.
License
MIT
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables read-only access to Obsidian vaults with semantic search, tag filtering, and metadata queries. Provides secure, intelligent note retrieval and summarization for LLMs without modifying your vault.