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

Tool	Description
vault_get_file	Get file content (raw markdown, JSON with metadata, or document map)
vault_create_file	Create or completely replace a file
vault_append_to_file	Append content to an existing or new file
vault_patch_file	Partially update a file (heading/block/frontmatter operations)
vault_delete_file	Delete a file from the vault

Directory Operations

Tool	Description
vault_list	List files and directories in the vault

Search Operations

Tool	Description
search_simple	Simple text search with context
search_advanced	Advanced search using Dataview DQL or JsonLogic

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

Variable	Description	Default
OBSIDIAN_API_URL	Obsidian REST API URL	http://127.0.0.1:27123
OBSIDIAN_API_KEY	API Key	(required)
MCP_TRANSPORT	stdio or http	stdio
MCP_PORT	Port for HTTP mode	3000
DEBUG	Enable debug logging	false

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