Obsidian Vault MCP Server

A Model Context Protocol (MCP) server that provides full programmatic access to an Obsidian vault through the Local REST API plugin. Runs as a Docker container and connects to Claude Desktop via stdio transport.

Tools (35)

System (3)

Tool	Description
get_server_status	Server version info and auth status
get_certificate	Download the self-signed TLS certificate
get_openapi_spec	Retrieve the OpenAPI YAML spec

Vault Files (6)

Tool	Description
read_note	Read a note (optional metadata: tags, frontmatter, stats)
get_document_map	Get headings, block references, and frontmatter fields
create_or_replace_note	Create a new note or overwrite an existing one
append_to_note	Append content to the end of a note
patch_note	Patch relative to a heading, block ref, or frontmatter field
delete_note	Delete a note

Vault Directories (2)

Tool	Description
list_vault_root	List files and folders in the vault root
list_directory	List files and folders in a specific directory

Active File (6)

Tool	Description
get_active_file	Get the currently open file (optional metadata)
get_active_file_map	Get the document map of the active file
replace_active_file	Replace the active file content
append_to_active_file	Append content to the active file
patch_active_file	Patch the active file at a heading, block, or frontmatter
delete_active_file	Delete the active file

Search (3)

Tool	Description
search_simple	Full-text search with surrounding context
search_dataview	Run a Dataview DQL TABLE query (requires Dataview plugin)
search_jsonlogic	Run a JsonLogic query against note metadata

Commands (2)

Tool	Description
list_commands	List all available Obsidian commands (including plugins)
execute_command	Execute a command by ID

Periodic Notes - Current Period (6)

Tool	Description
get_current_periodic_note	Get the current daily/weekly/monthly/quarterly/yearly note
get_current_periodic_note_map	Get the document map of the current periodic note
create_current_periodic_note	Create or replace the current periodic note
append_to_current_periodic_note	Append to the current periodic note
patch_current_periodic_note	Patch the current periodic note
delete_current_periodic_note	Delete the current periodic note

Periodic Notes - Specific Date (6)

Tool	Description
get_dated_periodic_note	Get a periodic note for a specific date
get_dated_periodic_note_map	Get the document map of a dated periodic note
create_dated_periodic_note	Create or replace a dated periodic note
append_to_dated_periodic_note	Append to a dated periodic note
patch_dated_periodic_note	Patch a dated periodic note
delete_dated_periodic_note	Delete a dated periodic note

Tags (1)

Tool	Description
get_tags	List all tags in the vault with usage counts

Navigation (1)

Tool	Description
open_note	Open a note in the Obsidian UI (optional new pane)

Prerequisites

Obsidian Setup

1. Install the Local REST API plugin:
   • Obsidian Plugin Page
   • GitHub Repository
   • API Documentation
2. Enable the plugin in Settings > Community Plugins
3. Go to Settings > Local REST API and copy the API Key
4. Note the HTTPS port (default: 27124)

Docker Setup

• Docker Desktop installed and running

Build

docker build -t obsidian-mcp-server:latest .

Connect to Claude Desktop

Add the following to your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OBSIDIAN_API_KEY=your-api-key-here",
        "-e", "OBSIDIAN_API_URL=https://host.docker.internal:27124",
        "--add-host=host.docker.internal:host-gateway",
        "obsidian-mcp-server:latest"
      ]
    }
  }
}

Replace your-api-key-here with the API key from the Obsidian plugin settings.

Restart Claude Desktop after saving.

Local Testing (without Docker)

export OBSIDIAN_API_KEY="your-api-key-here"
export OBSIDIAN_API_URL="https://127.0.0.1:27124"

pip install -r requirements.txt
python obsidian_server.py

# Test MCP handshake
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python obsidian_server.py

Environment Variables

Variable	Description	Default
OBSIDIAN_API_KEY	Bearer token from the Local REST API plugin	(required)
OBSIDIAN_API_URL	API base URL	https://host.docker.internal:27124

Usage Examples

In Claude Desktop, you can ask:

• "Read my note at Daily Notes/2026-03-30.md"
• "Create a new note called Ideas/Project Alpha.md with brainstorming content"
• "Append today's meeting notes to my daily note"
• "Search my vault for all notes mentioning 'Docker'"
• "List all files in my Projects folder"
• "What's currently open in Obsidian?"
• "Show me all my tags"
• "Get today's daily note with metadata"
• "Run a Dataview query to list all notes tagged #project"
• "Set the frontmatter field 'status' to 'complete' on my project note"
• "Open my weekly note in a new pane"

File Path Conventions

Rule	Example
Use forward slashes	folder/note.md
No leading slash	Daily/note.md not /Daily/note.md
Extensions required	note.md not note

Architecture

Claude Desktop  ->  MCP (stdio)  ->  Docker Container  ->  HTTPS  ->  Obsidian Local REST API  ->  Vault

The container reaches the host machine via host.docker.internal. The Local REST API uses a self-signed certificate, so SSL verification is disabled in the HTTP client.

Troubleshooting

Container Exits Immediately

This is normal when launched manually without stdin attached. Claude Desktop provides stdin via the stdio transport.

Connection Issues

• Verify the Local REST API plugin is enabled in Obsidian
• Test the API directly: curl -k https://127.0.0.1:27124/
• Ensure Docker Desktop is running

Authentication Errors

• Verify the API key matches what the plugin shows in Obsidian settings
• Check the container logs for OBSIDIAN_API_KEY not set warnings

Tools Not Appearing in Claude Desktop

• Verify the image is built: docker images | grep obsidian
• Check claude_desktop_config.json syntax is valid JSON
• Restart Claude Desktop completely (quit and reopen)

Security

• API key passed via environment variable, never hardcoded in source
• Container runs as non-root user (mcpuser, UID 1000)
• Local-only API access (not exposed to the internet)
• Vault files remain on the host filesystem
• Lock down config files: chmod 600 on any file containing the API key