MCP server for Obsidian

Archived: This project is no longer actively maintained. The approach of routing through a REST API plugin adds unnecessary complexity -- Obsidian vaults are markdown files on disk, and working with them directly via Obsidian's native CLI is simpler and more reliable. This repo remains available as a reference.

MCP server providing tools to interact with Obsidian via the Local REST API community plugin.

Note: This is a maintained fork of MarkusPfundstein/mcp-obsidian.

Installation

1. Install the Obsidian Plugin

Install and enable the Local REST API community plugin in Obsidian. Copy the API key from the plugin settings.

2. Add to Your MCP Client

Add this server to your MCP client configuration. Examples for common clients:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian-ek"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>"
      }
    }
  }
}

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian-ek"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>"
      }
    }
  }
}

Tip: If uvx isn't found, use which uvx to get the full path and use that instead.

Environment Variables

Requirements

The core Daily Notes plugin (built into Obsidian) is sufficient for daily periodic notes.

v1.0 Goal: Zero community plugin dependencies beyond Local REST API. All features will work with core Obsidian only.

Tools

18 tools organized by functionality:

File & Content Operations

Active Note & Periodic Notes

Commands & UI

Advanced

Example Prompts

File operations:

• "Get the contents of my last meeting note and summarize it"

• "Search for all files mentioning 'project deadlines'"

• "Create a new note called 'summary.md' with this content"

Active note & periodic notes:

• "What note do I have open? Summarize it"

• "Show me this week's weekly note"

• "What did I write in my daily notes last week?"

Commands & UI:

• "Open my project notes in a new tab"

• "Show me all available Obsidian commands"

Advanced Features

Path Encoding

Handles filenames with spaces, special characters, Unicode, and emojis:

Projects/2024 Q1/meeting notes.md
Área/configuração/São Paulo.md
Research (2024)/data #1 & analysis.md
Projects/documentation/notes.md

Template-Aware Heading Insertion

When using obsidian_patch_content to insert content under a heading that doesn't exist, the heading is auto-created in the correct position based on your template structure.

How it works:

1. Checks the note's frontmatter for a template: field

2. Falls back to folder convention: Daily Notes/*.md uses Templates/Daily Notes.md

3. Inserts new headings in template order (not appended to end)

Example: If your template has ## Todos, ## Notes, ## Journal and your note only has Todos and Journal, patching to "Notes" inserts it between them.

Parameters:

Project Status

This fork is in active development (v0.x.x). The API may change before v1.0.0.

Current (v0.6.x)

• 18 tools with ~30% reduced token footprint

• Template-aware heading insertion

• Robust path encoding

• Published to PyPI as mcp-obsidian-ek

Planned for v1.0.0

• Streamlined tool surface

• Published to PyPI

• Stable API contract

• Comprehensive test coverage

• No community plugin dependencies - remove Dataview requirement, use file metadata for recent changes

• Periodic notes via folder conventions (no Periodic Notes plugin required)

Breaking Changes from v0.4.x

These convenience tools were removed (use get_active/get_periodic_note + file operations instead):

• obsidian_post_active, obsidian_put_active, obsidian_patch_active, obsidian_delete_active

• obsidian_post_periodic, obsidian_put_periodic, obsidian_patch_periodic, obsidian_delete_periodic

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and how to add new tools.