A TypeScript MCP server to interact with Obsidian via Local REST API
Obsidian MCP Server (TypeScript)
A TypeScript MCP server to interact with Obsidian via the Local REST API community plugin.
Note: This is a TypeScript port of the original mcp-obsidian Python project by MarkusPfundstein. All credit for the original concept and API design goes to the original author.
Features
- 🚀 High Performance: LRU caching, request deduplication, and optimized batch processing
- 🔧 Type Safety: Full TypeScript with strict typing and comprehensive error handling
- 📋 Dynamic Tool Discovery: Automatically discovers and loads tools with metadata
- 🎯 Smart Error Handling: Simplified error responses with actionable suggestions
- 📦 Modular Architecture: Clean separation of concerns with reusable utilities
- 📊 MCP Resources: Read-only access to vault data through the resources protocol
- 📏 Resource Metadata: File size and last modified timestamps for better cache optimization
- ⚠️ Protocol-Compliant Errors: Standard MCP error codes for consistent error handling
Performance Optimization: Internal Resource Caching
The Obsidian MCP server automatically optimizes performance through intelligent internal resource caching. This system provides significant speed improvements for frequently used operations while remaining completely transparent to users.
Real-time Cache Synchronization
The server includes a sophisticated subscription system that automatically invalidates cached data when files change. This ensures you always see current data without manual cache clearing:
- Automatic Updates: File operations (create, update, delete) trigger immediate cache invalidation
- Smart Invalidation: Only affected caches are cleared, preserving unrelated cached data
- MCP Client Notifications: Connected clients receive real-time resource update notifications
- Zero Configuration: The subscription system works automatically with no setup required
For technical details, see the Subscription System Documentation.
How It Works
Several major tools now use internal MCP resources with smart caching instead of making direct API calls every time:
| Tool | Internal Resource | Cache Duration | Performance Benefit |
|---|---|---|---|
obsidian_get_all_tags |
vault://tags |
5 minutes | 10-50x faster for tag operations |
obsidian_get_recent_changes |
vault://recent |
30 seconds | Near-instant recent file listings with titles & previews |
obsidian_get_file_contents |
vault://note/{path} |
2 minutes | Dramatically faster for repeated file access |
obsidian_simple_search |
vault://search/{query} |
1 minute | Cached search results for common queries |
obsidian_list_files_in_vault |
vault://structure |
5 minutes | Instant vault browsing after first load |
obsidian_list_files_in_dir |
vault://folder/{path} |
2 minutes | Fast folder navigation |
User Benefits
- Transparent Performance: All speed improvements happen automatically - no configuration required
- Backward Compatible: Existing workflows continue to work exactly the same way
- Smart Invalidation: Cache automatically updates when you modify files through the tools
- Reduced API Load: Fewer direct calls to Obsidian's REST API improves overall responsiveness
- Better User Experience: Operations like browsing tags, searching, and accessing recent files feel instant
Technical Details
The optimization works by:
- Resource-First Strategy: Tools check internal MCP resources before making API calls
- Tiered Caching: Different cache durations based on data volatility (30s for recent changes, 5min for vault structure)
- Graceful Fallback: If resources aren't available, tools automatically fall back to direct API calls
- Memory Efficient: Uses LRU caching with automatic cleanup to prevent memory leaks
This optimization is part of our commitment to making the Obsidian MCP server both powerful and performant for daily use.
MCP Resource Enhancements
Resource Metadata (v2.3.0)
All MCP resources now include optional metadata in the _meta field, providing file size and modification timestamps without requiring additional API calls. This enables better cache optimization and resource management by clients.
Metadata Structure
{
"uri": "vault://note/meeting-notes.md",
"name": "Meeting Notes",
"mimeType": "text/plain",
"text": "# Meeting Notes\n...",
"_meta": {
"size": 2048, // File size in bytes
"sizeFormatted": "2.00 KB", // Human-readable size
"lastModified": "2025-10-07T14:30:00.000Z" // ISO 8601 timestamp (UTC)
}
}
Use Cases
- Cache Validation: Use
lastModifiedtimestamps to determine if cached resources are stale - Resource Filtering: Filter resources by size before fetching
Tools (6)
obsidian_get_all_tagsRetrieves all tags currently used in the Obsidian vault.obsidian_get_recent_changesLists files that have been recently modified in the vault.obsidian_get_file_contentsRetrieves the text content of a specific note or file by its path.obsidian_simple_searchPerforms a simple text search across the vault.obsidian_list_files_in_vaultLists all files and the overall structure of the vault.obsidian_list_files_in_dirLists all files within a specific directory path.Environment Variables
OBSIDIAN_API_KEYrequiredAPI key from the Local REST API community pluginOBSIDIAN_URLURL where Obsidian Local REST API is hosted (default: http://127.0.0.1:27124)Configuration
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@duquesnay/obsidian-mcp-ts"],
"env": {
"OBSIDIAN_API_KEY": "your_api_key_here",
"OBSIDIAN_URL": "http://127.0.0.1:27124"
}
}
}
}