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:

┌─────────────────────────────────────────┐
│           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

npm install
npm run build

Configuration

Create a obsidian-mcp.json configuration file:

{
  "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 (

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

# 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)

{
  "vaults": [
    {
      "name": "personal",
      "type": "local",
      "path": "/home/user/Documents/ObsidianVault"
    }
  ]
}

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

{
  "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

{
  "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)

{
  "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

npm start

Or use the binary:

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

npm run build

Watch Mode

npm run watch

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

// 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

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

await mcp.callTool('dataview_query', {
  query: {
    from: 'projects/',
    groupBy: 'status',
    select: ['title', 'modified', 'tags']
  }
});

Example: Get metadata from inline fields

// 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

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

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

await mcp.callTool('create_daily_note', {
  vault: 'my-vault'
});
// Creates: Daily Notes/2024-01-15.md

Example: Create this week's note

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

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:

{
  "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 - 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