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	Enabled
Inverted Index	Fast word-to-files lookup	Enabled
Path Trie	Efficient glob pattern matching	Enabled
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`	`true`	Enable LMDB persistence
`OBSIDIAN_ENABLE_INVERTED_INDEX`	`true`	Enable fast text search index
`OBSIDIAN_ENABLE_PATH_TRIE`	`true`	Enable fast glob matching
`OBSIDIAN_ENABLE_CACHE_WARMUP`	`false`	Pre-load cache on startup

See Configuration Reference for all 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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Obsidian MCP Server

Obsidian MCP Server

Features

Quick Start

Installation

Configuration

Available Tools

Architecture

Performance Features

Configuration Quick Reference

Development

Project Structure

Documentation

Security

Contributing

Latest Blog Posts

MCP directory API