Obsidi MCP

Expose Obsidian vault tools via Model Context Protocol (MCP) server.

Features

• MCP Server - Serve vault tools over stdio, HTTP (StreamableHTTP), or SSE transports
• 28+ Built-in Tools - Read, write, search, tag, link, and manage vault notes
• CLI Bridge - Obsidian Sync history, file recovery, and diff tools (v1.12+)
• Tool Provider Registry - Other plugins register additional tools at runtime
• Vault Resources - MCP resource subscriptions with live vault change notifications
• Session Persistence - Hot-reload recovery for connected MCP clients

Requirements

• Obsidian Desktop (not mobile - uses Node.js features)
• Node.js 18+
• For CLI bridge: Obsidian CLI v1.12+

Installation

BRAT (Recommended)

Install via BRAT:

1. Install BRAT from Community Plugins
2. Add cameronsjo/obsidi-mcp as a beta plugin
3. Enable Obsidi MCP in Community Plugins

Development

git clone https://github.com/cameronsjo/obsidi-mcp.git
cd obsidi-mcp

npm install
npm run build

# For development with auto-rebuild
npm run dev

Linking to Obsidian

Create a symlink from your Obsidian vault's plugins folder:

ln -sfn /path/to/obsidi-mcp /path/to/vault/.obsidian/plugins/obsidi-mcp

Usage

1. Enable the plugin in Obsidian Settings > Community Plugins
2. Configure transport (stdio, HTTP, or SSE) in plugin settings
3. Connect your MCP client to the server

Connecting Claude Code

For stdio transport, add to your Claude Code MCP config:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian",
      "args": ["--vault", "Your Vault Name", "--mcp"]
    }
  }
}

For HTTP transport:

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3000/mcp",
      "transport": "streamable-http"
    }
  }
}

Configuration

Open Settings > Obsidi MCP to configure:

• Transport: stdio, HTTP (StreamableHTTP), SSE, or stdio + HTTP
• HTTP Port: Port for HTTP/SSE server (default: 3000)
• Server Name: Name exposed to MCP clients
• CLI Bridge: Enable Obsidian CLI tools for Sync history and file recovery

Tools Available

Vault Tools (28)

Category	Tools
Read	read_note, read_note_range, get_note_metadata, get_active_note
Write	create_note, modify_note, append_to_note, delete_note, rename
Search	search_vault, search_by_tag, search_by_date
Navigation	list_notes, list_folder, get_backlinks, get_outgoing_links
Tags	list_all_tags, manage_tags
Links	suggest_links, check_broken_links
Metadata	get_vault_stats, get_instructions
Semantic	semantic_search, find_similar (requires RAG provider)

CLI Bridge Tools (7)

Tool	Description
sync_status	Check Obsidian Sync connection status
sync_history	Get version history for a file
sync_read	Read a specific version of a file
sync_restore	Restore a file to a previous version
file_diff	Diff between two versions of a file
file_history	Get file modification history
file_history_read	Read a file at a specific history point

Plugin Integration

Other plugins can register tools with Obsidi MCP:

// In your plugin's onload()
const mcp = this.app.plugins?.plugins?.['obsidi-mcp'];
if (mcp?.registerToolProvider) {
  mcp.registerToolProvider({
    id: 'my-plugin',
    name: 'My Plugin',
    tools: myToolDefinitions,
  });
}

// In your plugin's onunload()
const mcp = this.app.plugins?.plugins?.['obsidi-mcp'];
mcp?.unregisterToolProvider?.('my-plugin');

Tool providers registered later override built-in tools with the same name, enabling plugins to provide enhanced versions (e.g., RAG-powered search).

Architecture

obsidi-mcp
├── MCPServer (stdio/HTTP/SSE transports)
│   ├── Tool dispatch (dynamic from registry)
│   ├── Vault resources (live subscriptions)
│   ├── Completions (path autocomplete)
│   ├── Elicitation (confirmation dialogs)
│   └── Log forwarding
├── ObsidianTools (28 built-in vault tools)
├── CLI Bridge (7 Obsidian CLI tools)
├── VaultResources (direct app.vault access)
└── Tool Provider Registry
    ├── Built-in tools (layer 1)
    ├── CLI bridge tools (layer 2)
    └── External providers (layer 3, last wins)

Security

The HTTP/SSE server binds to localhost with no authentication, no TLS, and no access control. It is designed for local-only use by MCP clients running on the same machine.

Do not expose the server to a network without a secured reverse proxy. Anyone who can reach the HTTP port has full read/write access to your vault.

If you need remote access, place the server behind a reverse proxy that provides authentication, TLS, rate limiting, and role-based access control (e.g., Caddy, nginx, Cloudflare Tunnel).

Troubleshooting

Server not starting

Check Obsidian's developer console (Cmd+Option+I) for errors. The server status is visible in plugin settings.

CLI bridge not available

Ensure Obsidian CLI is installed (v1.12+):

obsidian --version

Port already in use

Change the HTTP port in plugin settings if port 3000 is occupied.

License

PolyForm Noncommercial 1.0.0