Obsidian MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Obsidian vaults via direct filesystem access, enabling AI assistants to interact with your notes and knowledge base.

Features

• Note Management: Create, read, update, and delete notes
• Folder Operations: Create, rename, move, and delete folders
• Vault Search: Search with glob patterns, regex, tags, frontmatter, and relevance scoring
• Intelligent Caching: Multi-layer caching with optional LMDB persistence
• Real-Time Monitoring: File watching for automatic cache invalidation

Quick Start

Installation

npm install
npm run build

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/build/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

See Configuration Reference for all options.

Available Tools

Tool	Description
list_notes	List all notes in the vault
read_note	Read the content of a note
create_note	Create a new note
update_note	Update an existing note
delete_note	Delete a note
get_note_metadata	Get frontmatter and tags
search_vault	Search with required query
advanced_search_vault	Advanced search with all options
search_vault_stream	Streaming search for large vaults
manage_folder	Create, rename, move, or delete folders
get_cache_stats	Get cache performance statistics

See Tools Reference for detailed documentation.

Architecture

flowchart TB
    subgraph tools [MCP Tools]
        T1[search_vault]
        T2[read_note]
        T3[list_notes]
    end
    
    subgraph caching [Caching Layer]
        FC[FileListCache]
        CC[ContentCache]
        SC[SearchResultCache]
        PC[PersistentCache]
    end
    
    subgraph optimization [Search Optimization]
        II[InvertedIndex]
        PT[PathTrie]
    end
    
    subgraph fs [Filesystem]
        V[(Obsidian Vault)]
        FW[FileWatcher]
    end
    
    T1 --> SC
    T1 --> II
    T1 --> PT
    T2 --> CC
    T3 --> FC
    
    CC --> PC
    FC --> PC
    SC --> PC
    
    FW --> FC
    FW --> CC
    FW --> II
    
    V --> FW

See Features Reference for detailed architecture documentation.

Performance Features

Feature	Description	Default
File List Cache	Cache folder listings	60s TTL
Content Cache	LRU cache for file contents	100 entries
Search Result Cache	Cache search query results	50 entries
Persistent Cache	LMDB-backed persistence	Disabled
Inverted Index	Fast word-to-files lookup	Disabled
Path Trie	Efficient glob pattern matching	Disabled
File Watcher	Real-time cache invalidation	Enabled
Cache Warmup	Pre-load cache on startup	Disabled

Configuration Quick Reference

Variable	Default	Description
OBSIDIAN_VAULT_PATH	Required	Path to your Obsidian vault
OBSIDIAN_ENABLE_PERSISTENT_CACHE	false	Enable LMDB persistence
OBSIDIAN_ENABLE_INVERTED_INDEX	false	Enable fast text search index
OBSIDIAN_ENABLE_PATH_TRIE	false	Enable fast glob matching
OBSIDIAN_ENABLE_CACHE_WARMUP	false	Pre-load cache on startup

See Configuration Reference for all 19 environment variables.

Development

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test

Project Structure

src/
├── config/                    # Configuration management
├── handlers/                  # MCP request handlers
├── services/
│   ├── cache/                 # Caching services
│   ├── search/                # Search optimization services
│   ├── fileSystem.ts          # Core filesystem operations
│   ├── FileWatcher.ts         # File change monitoring
│   └── FrontmatterParser.ts   # YAML frontmatter parsing
├── types/                     # TypeScript type definitions
├── index.ts                   # Entry point
└── server.ts                  # Main server class

Documentation

• Tools Reference - All available MCP tools
• Features Reference - Internal features and architecture
• Configuration Reference - All environment variables

Security

• Operations are restricted to the configured vault path
• Path traversal protection is implemented
• Consider running in a sandboxed environment for production use

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request