obsidian-mcp-rest

A lightweight MCP (Model Context Protocol) server for Obsidian, built as a thin wrapper over the Obsidian REST API.

Also available as an Obsidian plugin with settings UI, auto-detection of obsidian-api, and one-click MCP server installation.

Zero npm dependencies. Node.js built-ins only.

Features

• 18 MCP tools — full vault CRUD, search, templates, active file operations
• MCP prompts — auto-discovery of prompt templates from vault
• Obsidian plugin — settings tab with auto-detect, install, and copyable config
• Zero dependencies — uses only Node.js built-in modules
• UTF-8 correct — all markdown operations preserve Unicode properly
• PATCH v3 — heading/block/frontmatter targeting + search-replace for precise text substitution
• Web fetch — built-in HTML to Markdown conversion

Requirements

• Node.js >= 20
• obsidian-api plugin (or obsidian-local-rest-api)
• API key configured in the plugin settings
• Optionally: Smart Connections plugin (for search_vault_smart)
• Optionally: Templater plugin (for execute_template and prompts)

Installation

As MCP server

npx -y @swarogan/obsidian-mcp-rest

As Obsidian plugin

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create <vault>/.obsidian/plugins/obsidian-mcp-rest/ and place the files there
3. Enable the plugin in Obsidian settings
4. The plugin auto-detects obsidian-api settings and provides a copyable MCP config

Configuration

Set environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OBSIDIAN_API_KEY | Yes | — | Bearer token from plugin settings | | OBSIDIAN_REST_URL | No | https://127.0.0.1:27124 | Obsidian REST API URL | | OBSIDIAN_REQUEST_TIMEOUT_MS | No | 30000 | Request timeout in ms |

MCP Client Configuration

Claude Code

claude mcp add obsidian -e OBSIDIAN_API_KEY="your-api-key" -- npx -y @swarogan/obsidian-mcp-rest

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@swarogan/obsidian-mcp-rest"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_REST_URL": "https://127.0.0.1:27124"
      }
    }
  }
}

Available MCP Tools

Server

• get_server_info — API status (no auth required)

Active File

• get_active_file — read current file (markdown or JSON)
• update_active_file — replace entire content
• append_to_active_file — append content
• patch_active_file — patch heading/block/frontmatter or search-replace text
• delete_active_file — delete current file
• show_file_in_obsidian — open file in Obsidian UI

Vault Files

• list_vault_files — list directory contents
• get_vault_file — read file by path
• create_vault_file — create or overwrite file
• append_to_vault_file — append to file
• patch_vault_file — patch heading/block/frontmatter or search-replace text
• delete_vault_file — delete file

Search

• search_vault — Dataview DQL or JsonLogic queries
• search_vault_simple — full-text search with context
• search_vault_smart — semantic search (requires Smart Connections)

Other

• execute_template — run Templater templates with arguments
• fetch — download web content, convert HTML to markdown

MCP Prompts

The server supports MCP prompts capability:

• Auto-discovers .md files in Prompts/ directory with obsidian-mcp-rest-prompt tag
• Parses tp.mcpTools.prompt(...) calls for argument definitions
• Executes templates via Templater plugin
• Strips frontmatter from output

Tests

npm test

28 tests covering tools, prompts, client, UTF-8, PATCH operations, and stdio transport.

Network Usage

This MCP server communicates only with the local Obsidian REST API (default 127.0.0.1:27124). It does not connect to any external services.

The fetch tool makes outbound HTTP requests only when explicitly invoked by the user.

Support

If this project is useful to you and you'd like to support further development, you can do so on Ko-fi.

License

MIT