Obsidian MCP Server

A comprehensive Model Context Protocol (MCP) server for Obsidian that provides powerful vault access, knowledge graph analysis, and advanced integration features.

📚 Documentation

• Quick Start Guide - Get up and running in 5 minutes

• Claude Desktop Setup - Connect to Claude Desktop

• Vault Types Explained - Understanding local/remote/API configurations

• Testing Guide - Running tests and contributing

• API Documentation - 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:

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

Configuration

Create a obsidian-mcp.json configuration file:

Vault Types Explained

Local Vault (

• 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 (

• 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:

Common Configuration Scenarios

Scenario 1: Just a local vault (most common)

Scenario 2: Local vault + iCloud/Dropbox (also use local type)

Note: iCloud/Dropbox sync is handled by the cloud service itself - just point to the synced folder.

Scenario 3: Multiple local vaults

Scenario 4: Self-hosted remote server (advanced)

Note: Requires you to implement or deploy a compatible REST API server.

Usage

Start the Server

Or use the binary:

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:

Development

Project Structure

Build

Watch Mode

Integration with Obsidian

For advanced features, install the 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

Dataview Queries

Query your notes like a database with SQL-like syntax:

Example: Find recent project notes

Example: Group notes by tag

Example: Get metadata from inline fields

Template System

Create reusable templates with variable substitution and automatic date handling:

Example: Create a meeting note template

Example: Use the template

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

Example: Create this week's note

Example: List all monthly notes

Configuration: Periodic notes can be configured with custom folders, formats, and templates:

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 - The knowledge base application

• Obsidian Local REST API - REST API plugin

• Model Context Protocol - MCP specification

Support

For issues and questions:

• GitHub Issues: Create an issue

• Documentation: See this README

Built with ❤️ for the Obsidian and MCP communities