Skip to main content
Glama
Obsidian MCP Server

Obsidian MCP Server

by derrikjb

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

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

Available Tools

8 tools
search_advancedA

Perform an advanced search using Dataview DQL or JsonLogic. Dataview is best for querying metadata and frontmatter (e.g., "TABLE FROM #tag"). JsonLogic is best for complex logical queries on note properties.

Inputs: no named parameters.

search_simpleA

Perform a simple text search across all files in the vault. Returns matching files with context around each match. Best for straightforward text searches.

Inputs: no named parameters.

vault_append_to_fileA

Append content to the end of an existing file. If the file doesn't exist, it will be created. Use this to add content without replacing existing content.

Inputs: no named parameters.

vault_create_fileA

Create a new file in the vault or completely replace an existing file's content. Use this when you want to write the entire file content at once.

Inputs: no named parameters.

vault_delete_fileA

Delete a file from the Obsidian vault. This operation cannot be undone.

Inputs: no named parameters.

vault_get_fileA

Get the content of a file from the Obsidian vault. Can return raw markdown, parsed JSON with metadata (tags, frontmatter, stats), or a document map showing headings, blocks, and frontmatter fields.

Inputs: no named parameters.

vault_listA

List files and directories in the Obsidian vault. Returns a formatted list showing directories (ending with /) and files. Use this to explore the vault structure.

Inputs: no named parameters.

vault_patch_fileA

Partially update a file by inserting content relative to a heading, block reference, or frontmatter field. Operations: append (after target), prepend (before target), or replace. Useful for updating specific sections without rewriting the entire file.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. The two search tools are well-differentiated (advanced vs. simple), and the file operation tools each handle specific actions (create, get, append, patch, delete, list) without overlap. Descriptions clearly indicate when to use each tool.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout. The 'vault_' prefix groups related file operations, while 'search_' prefixes distinguish query tools, creating a predictable and readable naming convention across all 8 tools.

    Tool Count5/5

    8 tools is well-scoped for an Obsidian vault management server. This provides complete coverage for core operations (search, file CRUD, vault exploration) without being overwhelming. Each tool earns its place with clear utility for the domain.

    Completeness5/5

    The toolset provides complete coverage for Obsidian vault operations. It includes search capabilities (simple and advanced), full file lifecycle management (create, get, append, patch, delete), and vault exploration (list). No obvious gaps exist for the stated purpose of managing an Obsidian vault.

    Related MCP Connectors