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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request