Obsidian MCP Server

A modern Model Context Protocol (MCP) server that integrates with the Obsidian Local REST API to read, create, and edit notes effectively within Obsidian.

Features

This MCP server provides the following tools:

Vault File Operations

Directory Operations

Search Operations

Prerequisites

1. Obsidian with the Local REST API plugin installed and enabled
2. Node.js v18 or higher
3. API Key from Obsidian's Local REST API settings

Quick Start

npm install
npm run build
npm run setup

The interactive setup wizard will guide you through:

• Entering your Obsidian API Key
• Selecting transport mode (stdio for Claude Desktop, HTTP for Open WebUI)
• Configuring optional settings

After setup, start the server:

# For Open WebUI (HTTP mode)
npm run start:http

# For Claude Desktop (stdio mode)
npm start

Installation

npm install
npm run build

Configuration

Setup Wizard (Recommended)

Run the interactive setup wizard:

npm run setup

This creates a .env file with your configuration.

Manual Configuration

Alternatively, copy .env.example to .env and edit manually:

cp .env.example .env

Environment Variables

Usage with MCP Clients

Claude Desktop (stdio mode)

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/Obsidian_MCP/dist/index.js"],
      "env": {
        "OBSIDIAN_API_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

Open WebUI (HTTP mode)

1. Start the server in HTTP mode:

   npm run start:http
   

2. In Open WebUI, go to Admin Settings → Tools → MCP Servers

3. Add a new MCP server:

   • Type: MCP Streamable HTTP
   • URL: http://localhost:3000/mcp
   • Auth: None (the server handles Obsidian auth internally)

4. Click Save

Startup Health Check

When the server starts, it automatically verifies the connection to Obsidian:

========================================
  Obsidian MCP Server - Startup Check
========================================
API URL: http://127.0.0.1:27123
Debug Mode: disabled

Checking connection to Obsidian REST API...
✓ Connected to Obsidian REST API
✓ Authenticated successfully
  Plugin Version: 3.4.2
  Obsidian Version: 1.11.7

If there are connection issues, troubleshooting steps are displayed.

Debug Mode

Enable debug logging for verbose output:

DEBUG=true npm start

Shows detailed logs for API requests, tool calls, and HTTP connections.

Troubleshooting

Open WebUI Connection Failed

1. Verify server is running:

   curl http://localhost:3000/health
   

2. Check configuration:

   • URL: http://localhost:3000/mcp
   • Auth: None (not Bearer)
   • Type: MCP Streamable HTTP

3. Test the endpoint: The /mcp endpoint accepts POST requests with MCP protocol messages.

General Issues

1. Ensure Obsidian is running with Local REST API plugin enabled
2. Verify API key is correct
3. Try DEBUG=true npm start for detailed logs
4. Re-run setup: npm run setup

Tool Details

vault_get_file

Get file content with optional format:

• markdown (default): Raw markdown content
• json: Parsed note with metadata
• document-map: Shows headings, blocks, frontmatter fields

vault_patch_file

Partial updates without rewriting entire file:

• Operations: append, prepend, replace
• Targets: headings, block references, frontmatter fields

search_advanced

• Dataview DQL: TABLE FROM #tag WHERE field = value
• JsonLogic: {"in": ["myTag", {"var": "tags"}]}

Development

# Build
npm run build

# Development with auto-rebuild
npm run dev          # stdio mode
npm run dev:http     # HTTP mode

# Setup wizard
npm run setup

# Clean build artifacts
npm run clean

License

MIT