Obsidian MCP Server

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:

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:

1. Resource-First Strategy: Tools check internal MCP resources before making API calls
2. Tiered Caching: Different cache durations based on data volatility (30s for recent changes, 5min for vault structure)
3. Graceful Fallback: If resources aren't available, tools automatically fall back to direct API calls
4. 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 lastModified timestamps to determine if cached resources are stale
• Resource Filtering: Filter resources by size before fetching