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

Variable	Required	Default	Description
OBSIDIAN_API_KEY	Yes	—	API key from Local REST API plugin
OBSIDIAN_HOST	No	127.0.0.1	Obsidian host address
OBSIDIAN_PORT	No	27124	Obsidian REST API port

Requirements

Obsidian Plugin	Required	Notes
Local REST API	Yes	v3.0+ recommended
Periodic Notes	Optional	For weekly/monthly/quarterly/yearly (being removed in v1.0)
Dataview	Optional	For get_recent_changes tool (being removed in v1.0)

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

Tool	Description
obsidian_list_files_in_vault	List all files and directories in vault root
obsidian_list_files_in_dir	List files in a specific directory
obsidian_get_file_contents	Get content of a single file
obsidian_batch_get_file_contents	Get contents of multiple files
obsidian_simple_search	Text search across all files
obsidian_complex_search	JsonLogic queries with glob/regexp
obsidian_append_content	Append to a file
obsidian_patch_content	Insert content relative to heading/block/frontmatter
obsidian_put_content	Create or replace a file
obsidian_delete_file	Delete a file or directory

Active Note & Periodic Notes

Tool	Description
obsidian_get_active	Get the currently open note
obsidian_get_periodic_note	Get daily/weekly/monthly/quarterly/yearly note
obsidian_get_recent_periodic_notes	Get recent periodic notes

Commands & UI

Tool	Description
obsidian_get_commands	List available Obsidian commands
obsidian_execute_command	Execute a command by ID
obsidian_open_file	Open a file in Obsidian UI

Advanced

Tool	Description
obsidian_get_recent_changes	Recently modified files (requires Dataview)
obsidian_dataview_query	Execute DQL queries (requires Dataview)

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:

Parameter	Default	Description
create_heading_if_missing	true	Auto-create missing headings
template_path	auto	Explicit template path
use_template	true	Use template for positioning

---

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.