Obsidian MCP Server

# Obsidian MCP Server [](https://github.com/YOUR_USERNAME/obsidian-mcp/actions/workflows/test.yml) A comprehensive Model Context Protocol (MCP) server for [Obsidian](https://obsidian.md/) that provides powerful vault access, knowledge graph analysis, and advanced integration features. ## 📚 Documentation - **[Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes - **[Claude Desktop Setup](./CLAUDE_DESKTOP_SETUP.md)** - Connect to Claude Desktop - **[Vault Types Explained](./VAULT_TYPES.md)** - Understanding local/remote/API configurations - **[Testing Guide](./TESTING.md)** - Running tests and contributing - **[API Documentation](./README.md#available-tools)** - Complete tool reference ## Features ### 🗂️ Multi-Vault Support - **Local Vaults**: Direct file system access with real-time file watching - **Remote Vaults**: HTTP/REST API integration with automatic sync - Seamless switching between multiple vaults ### 🔗 Knowledge Graph - Build and analyze complete knowledge graphs from your notes - Find related notes based on links, tags, and content similarity - Analyze graph structure (hubs, orphan notes, clusters) - Suggest potential links between related notes - Path finding between notes ### 🔍 Advanced Search - Full-text search across all notes - Filter by tags, folders, and metadata - Server-side and client-side search strategies ### 📝 Note Operations - Read, create, update, and delete notes - Parse Obsidian-flavored markdown with frontmatter - Extract and track internal links, embeds, and tags - Automatic backlink generation ### 📊 Analytics - Vault statistics (note count, word count, link count) - Tag usage analysis - Folder structure insights ### 🎯 Obsidian Integration - Optional integration with community "Local REST API" plugin - Open notes directly in Obsidian app - Execute Obsidian commands - Create daily notes - Access to Obsidian URI protocol - **Note:** Requires plugin installation and app running locally ### 🎨 Canvas Support - Read and manipulate Obsidian Canvas files - Create and edit canvas nodes (file, text, link, group) - Manage canvas edges and connections - Full graph visualization support - Programmatic canvas generation ### 📊 Dataview Queries - SQL-like querying over your notes - Filter by frontmatter metadata and inline fields - Sort and group results - Field selection and aggregation - Support for complex WHERE clauses - Extract metadata from notes (frontmatter + inline fields) ### 📝 Template System - Dynamic template rendering with variable substitution - Built-in date/time variables (`{{date}}`, `{{time}}`, `{{weekday}}`, etc.) - Custom variable support - Default values (`{{variable|default}}`) - Date formatting (`{{date:YYYY-MM-DD}}`) - Frontmatter merging - Create notes from templates programmatically ### 📅 Periodic Notes - Daily, weekly, monthly, and yearly notes - Automatic date-based naming and organization - Custom templates for each note type - Date range calculations - List and query periodic notes - Configurable folder structure and formats ## Architecture The server is built with a clean, modular architecture: ``` ┌─────────────────────────────────────────┐ │ MCP Server Layer │ │ (Tools, Resources, Protocol Handling) │ └──────────────┬──────────────────────────┘ │ ┌──────────────┴──────────────────────────┐ │ Service Layer │ │ • Knowledge Graph Service │ │ • Canvas Service │ │ • Dataview Service │ │ • Template Service │ │ • Periodic Notes Service │ │ • Configuration Management │ └──────────────┬──────────────────────────┘ │ ┌──────────────┴──────────────────────────┐ │ Connector Layer (Adapters) │ │ • Local Vault Connector (File System) │ │ • Remote Vault Connector (HTTP API) │ └──────────────┬──────────────────────────┘ │ ┌──────────────┴──────────────────────────┐ │ Integration Layer │ │ • Obsidian API Client │ │ • Markdown Parser │ └──────────────────────────────────────────┘ ``` ### Key Design Patterns - **Adapter Pattern**: Abstract `BaseConnector` interface allows seamless switching between local and remote vaults - **Service Layer**: Separates business logic (knowledge graph) from data access - **Configuration Management**: Flexible config from files, environment, or defaults - **Real-time Updates**: File watchers for local vaults, periodic sync for remote ## Installation ```bash npm install npm run build ``` ## Configuration Create a `obsidian-mcp.json` configuration file: ```json { "vaults": [ { "name": "my-local-vault", "type": "local", "path": "/path/to/obsidian/vault" }, { "name": "my-cloud-vault", "type": "remote", "url": "https://your-sync-server.com/api", "apiKey": "your-api-key", "syncInterval": 60000 } ], "obsidianApi": { "restApiUrl": "http://localhost:27124", "apiKey": "your-api-key", "vaultName": "my-local-vault" }, "server": { "name": "obsidian-mcp-server", "version": "1.0.0" } } ``` ### Vault Types Explained **Local Vault (`type: "local"`)** - Direct filesystem access to your Obsidian vault folder - Fastest performance, real-time file watching - Use this for vaults stored on your computer or mounted network drives **Remote Vault (`type: "remote"`)** - Connects to a self-hosted sync server via HTTP/REST API - For vaults hosted on your own cloud infrastructure (not Obsidian's sync service) - Examples: Custom REST API, CouchDB, WebDAV wrapper, etc. - Requires you to implement or use a compatible sync server **Obsidian API (Optional)** - Only needed if you want to control the Obsidian desktop app - Requires the "Local REST API" community plugin in Obsidian - Enables: Opening notes in app, executing commands, accessing app features - NOT used for reading/writing vault content (use local/remote vaults for that) ### Configuration via Environment Variables Alternatively, use environment variables: ```bash # Local vault export OBSIDIAN_VAULT_PATH="/path/to/vault" export OBSIDIAN_VAULT_NAME="my-vault" # Remote vault export OBSIDIAN_REMOTE_URL="https://your-sync-server.com/api" export OBSIDIAN_REMOTE_NAME="cloud" export OBSIDIAN_REMOTE_API_KEY="your-key" export OBSIDIAN_SYNC_INTERVAL="60000" # Obsidian API (optional) export OBSIDIAN_API_URL="http://localhost:27124" export OBSIDIAN_API_KEY="your-key" ``` ### Common Configuration Scenarios **Scenario 1: Just a local vault (most common)** ```json { "vaults": [ { "name": "personal", "type": "local", "path": "/home/user/Documents/ObsidianVault" } ] } ``` **Scenario 2: Local vault + iCloud/Dropbox (also use local type)** ```json { "vaults": [ { "name": "synced", "type": "local", "path": "/home/user/iCloud/ObsidianVault" } ] } ``` Note: iCloud/Dropbox sync is handled by the cloud service itself - just point to the synced folder. **Scenario 3: Multiple local vaults** ```json { "vaults": [ { "name": "personal", "type": "local", "path": "/home/user/Documents/PersonalVault" }, { "name": "work", "type": "local", "path": "/home/user/Documents/WorkVault" } ] } ``` **Scenario 4: Self-hosted remote server (advanced)** ```json { "vaults": [ { "name": "cloud", "type": "remote", "url": "https://your-server.com/obsidian-api", "apiKey": "your-api-key", "syncInterval": 60000 } ] } ``` Note: Requires you to implement or deploy a compatible REST API server. ## Usage ### Start the Server ```bash npm start ``` Or use the binary: ```bash node dist/index.js ``` ### Available MCP Tools The server exposes the following tools through the MCP protocol: #### Note Operations - `get_note` - Retrieve a note by path - `search_notes` - Search notes with filters - `create_note` - Create a new note - `update_note` - Update existing note - `delete_note` - Delete a note #### Vault Information - `get_vault_stats` - Get vault statistics - `list_tags` - List all tags - `list_folders` - List all folders #### Knowledge Graph - `get_knowledge_graph` - Get complete graph structure - `get_related_notes` - Find related notes - `analyze_graph` - Analyze graph structure - `suggest_links` - Suggest potential links #### Canvas Operations - `get_canvas` - Read a canvas file - `create_canvas` - Create a new empty canvas - `list_canvas_files` - List all canvas files in vault - `add_canvas_node` - Add a node (file, text, link, or group) - `add_canvas_edge` - Add an edge/connection between nodes - `delete_canvas_node` - Delete a node from canvas - `delete_canvas_edge` - Delete an edge from canvas #### Dataview Queries - `dataview_query` - Execute Dataview-style queries on notes - `get_note_metadata` - Get metadata for a specific note - `get_unique_values` - Get all unique values for a field #### Template System - `list_templates` - List all available templates - `render_template` - Render a template with variables - `create_from_template` - Create a new note from a template #### Periodic Notes - `create_daily_note` - Create or get daily note - `create_weekly_note` - Create or get weekly note - `create_monthly_note` - Create or get monthly note - `create_yearly_note` - Create or get yearly note - `get_periodic_note_info` - Get info about a periodic note - `list_periodic_notes` - List periodic notes in a date range ### MCP Resources All notes are exposed as resources with URIs: ``` obsidian://{vault-name}/{note-path} ``` ## Development ### Project Structure ``` src/ ├── index.ts # Main MCP server ├── types/ # TypeScript type definitions │ ├── index.ts # Core types │ ├── canvas.ts # Canvas types │ ├── dataview.ts # Dataview types │ ├── template.ts # Template types │ └── periodic.ts # Periodic notes types ├── connectors/ # Vault connectors (adapters) │ ├── BaseConnector.ts │ ├── LocalConnector.ts │ └── RemoteConnector.ts ├── services/ # Business logic services │ ├── KnowledgeGraph.ts # Knowledge graph analysis │ ├── CanvasService.ts # Canvas file operations │ ├── DataviewService.ts # Dataview query processing │ ├── TemplateService.ts # Template rendering │ └── PeriodicNotesService.ts # Periodic notes management ├── api/ # External API integrations │ └── ObsidianAPI.ts └── utils/ # Utilities ├── config.ts └── markdown.ts ``` ### Build ```bash npm run build ``` ### Watch Mode ```bash npm run watch ``` ## Integration with Obsidian For advanced features, install the [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin: 1. Install the plugin from Obsidian Community Plugins 2. Enable the plugin and note the API key 3. Configure the `obsidianApi` section in your config ## Use Cases ### For AI Assistants - Access and navigate your Obsidian knowledge base - Create and update notes based on conversations - Find related information across notes - Suggest connections between ideas ### For Automation - Automated note creation and organization - Batch processing of notes - Knowledge graph analysis and visualization - Link maintenance and suggestions ### For Integrations - Connect Obsidian with other tools via MCP - Build custom workflows - Create dashboards and reports - Sync with external systems ## Advanced Features ### Canvas Support Obsidian Canvas is a powerful visual workspace. This server provides full programmatic access to create and manipulate canvas files: **Example: Create a visual mind map** ```typescript // Create a new canvas await mcp.callTool('create_canvas', { canvasPath: 'diagrams/mindmap.canvas' }); // Add nodes await mcp.callTool('add_canvas_node', { canvasPath: 'diagrams/mindmap.canvas', nodeType: 'file', file: 'notes/central-idea.md', x: 0, y: 0, width: 400, height: 200 }); await mcp.callTool('add_canvas_node', { canvasPath: 'diagrams/mindmap.canvas', nodeType: 'text', text: '# Key Concept', x: 500, y: 0, width: 300, height: 150, color: '1' // Red }); // Connect nodes with edges await mcp.callTool('add_canvas_edge', { canvasPath: 'diagrams/mindmap.canvas', fromNode: 'node-id-1', toNode: 'node-id-2', label: 'relates to' }); ``` ### Dataview Queries Query your notes like a database with SQL-like syntax: **Example: Find recent project notes** ```typescript await mcp.callTool('dataview_query', { query: { from: '#project', where: [ { field: 'status', operator: 'eq', value: 'active' }, { field: 'modified', operator: 'gte', value: '2024-01-01' } ], sort: [{ field: 'modified', direction: 'desc' }], limit: 10 } }); ``` **Example: Group notes by tag** ```typescript await mcp.callTool('dataview_query', { query: { from: 'projects/', groupBy: 'status', select: ['title', 'modified', 'tags'] } }); ``` **Example: Get metadata from inline fields** ```typescript // Note content: "Status:: In Progress\nPriority:: High" const metadata = await mcp.callTool('get_note_metadata', { notePath: 'projects/my-project.md' }); // Returns: { status: 'In Progress', priority: 'High', ... } ``` ### Template System Create reusable templates with variable substitution and automatic date handling: **Example: Create a meeting note template** ```markdown --- tags: [meeting] templateVariables: - name: attendees type: string description: Meeting attendees --- # Meeting: {{title}} **Date:** {{date}} **Time:** {{time}} **Attendees:** {{attendees|TBD}} ## Agenda - ## Notes ## Action Items - [ ] ``` **Example: Use the template** ```typescript await mcp.callTool('create_from_template', { templatePath: 'Templates/meeting.md', targetPath: 'Meetings/2024-01-15-team-sync.md', variables: { attendees: 'Alice, Bob, Charlie' }, frontmatter: { project: 'Q1 Planning' } }); ``` **Built-in Variables:** - `{{date}}` - Current date (YYYY-MM-DD) - `{{time}}` - Current time (HH:mm) - `{{datetime}}` - Current datetime - `{{year}}`, `{{month}}`, `{{day}}` - Date components - `{{weekday}}` - Day of week (Monday, Tuesday, etc.) - `{{week}}` - Week number (01-53) - `{{title}}`, `{{filename}}`, `{{folder}}` - File context ### Periodic Notes Automatically create and organize daily, weekly, monthly, and yearly notes: **Example: Create today's daily note** ```typescript await mcp.callTool('create_daily_note', { vault: 'my-vault' }); // Creates: Daily Notes/2024-01-15.md ``` **Example: Create this week's note** ```typescript await mcp.callTool('create_weekly_note', { vault: 'my-vault', variables: { goals: 'Complete project proposal' } }); // Creates: Weekly Notes/2024-W03.md ``` **Example: List all monthly notes** ```typescript await mcp.callTool('list_periodic_notes', { vault: 'my-vault', type: 'monthly', startDate: '2024-01-01', endDate: '2024-12-31' }); ``` **Configuration:** Periodic notes can be configured with custom folders, formats, and templates: ```json { "periodicNotes": { "daily": { "folder": "Journal/Daily", "format": "YYYY-MM-DD", "template": "Templates/daily-note.md" }, "weekly": { "folder": "Journal/Weekly", "format": "YYYY-[W]WW" } } } ``` ## Technical Highlights ### Markdown Parsing - Full support for Obsidian-flavored markdown - Frontmatter extraction (YAML) - Internal link parsing (`[[link]]`, `[[link|alias]]`) - Embed detection (`![[embed]]`) - Tag extraction (`#tag`, `#nested/tag`) - Inline field parsing (`key:: value` pattern) ### Canvas Operations - Complete Canvas file format support (JSON-based) - All node types: file, text, link, group - Edge/connection management with customization - Color and styling support - Programmatic canvas generation ### Dataview Integration - SQL-like query language for notes - Multiple filter operators (eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith, exists) - Sorting and grouping capabilities - Field selection and projection - Support for frontmatter and inline fields - Nested field access with dot notation ### Template System - Variable substitution with `{{variable}}` syntax - Built-in date/time variables with formatting - Default values: `{{variable|default}}` - Date formatting: `{{date:YYYY-MM-DD}}` - Frontmatter merging and manipulation - Template discovery and listing ### Periodic Notes - Automatic date-based note generation - Configurable folder structure and naming - Template integration for custom layouts - Date range calculations (daily, weekly, monthly, yearly) - ISO week number support - Flexible date format patterns ### Link Resolution - Smart link resolution (title-based and path-based) - Automatic backlink generation - Bidirectional link tracking ### Performance - Efficient caching strategies - File watching for instant updates - Lazy loading and pagination support ## Security Considerations - Local vaults: Requires file system access to vault directory - Remote vaults: Use HTTPS and secure API keys - API keys: Never commit to version control - File watching: Only monitors `.md` files ## Requirements - Node.js 18 or higher - TypeScript 5.x - Access to Obsidian vault(s) ## License MIT ## Contributing Contributions are welcome! Please feel free to submit issues and pull requests. ## Related Projects - [Obsidian](https://obsidian.md/) - The knowledge base application - [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) - REST API plugin - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification ## Support For issues and questions: - GitHub Issues: [Create an issue](https://github.com/yourusername/obsidian-mcp/issues) - Documentation: See this README --- Built with ❤️ for the Obsidian and MCP communities