Obsidian MCP Server

An MCP (Model Context Protocol) server that enables AI agents to perform sophisticated knowledge discovery and analysis across your Obsidian vault through the Local REST API plugin.

Why This Matters

This server transforms your Obsidian vault into a powerful knowledge base for AI agents, enabling complex multi-step workflows like:

• "Retrieve notes from my 'Projects/Planning' folder containing 'roadmap' or 'timeline' in titles, created after April 1st, then analyze them for any blockers or dependencies and present a consolidated risk assessment with references to the source notes"

• "Find all notes tagged with 'research' or 'analysis' from the last month, scan their content for incomplete sections or open questions, then cross-reference with my 'Team/Expertise' notes to suggest which colleagues could help address each gap"

• "Get the complete content of meeting notes from 'Leadership/Quarterly' containing 'budget' or 'headcount', analyze them for action items assigned to my department, and create a chronological timeline with source note references"

The server's advanced filtering, regex support, and full content retrieval capabilities allow agents to perform nuanced knowledge work that would take hours manually.

Prerequisites

1. Install the Obsidian Local REST API plugin in your Obsidian vault
2. Configure and enable the plugin in Obsidian settings
3. Note the API URL (default: https://localhost:27124) and API key if you've set one

Installation

From PyPI (Recommended)

# Install from PyPI
pip install obsidian-api-mcp-server

# Or with uv
uv pip install obsidian-api-mcp-server

Add to MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "obsidian-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "obsidian-api-mcp-server>=1.0.1",
        "obsidian-api-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://localhost:27124",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

From Source (Development)

# Clone the repository
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

Configuration

Set environment variables for the Obsidian API:

# Required: Obsidian API URL (HTTPS by default)
export OBSIDIAN_API_URL="https://localhost:27124"  # Default

# Optional: API key if you've configured authentication
export OBSIDIAN_API_KEY="your-api-key-here"

Important Security Note: Avoid hardcoding your OBSIDIAN_API_KEY directly into scripts or committing it to version control. Consider using a .env file (which is included in the .gitignore of this project) and a library like python-dotenv to manage your API key, or use environment variables managed by your operating system or shell.

Note: The server defaults to HTTPS and disables SSL certificate verification for self-signed certificates commonly used with local Obsidian instances. For HTTP connections, set OBSIDIAN_API_URL="http://localhost:27123".

Usage

Run the MCP server:

obsidian-mcp

Available Tools

The server provides three powerful tools:

1. search_vault - Advanced search with flexible filters and full content retrieval:
   • query - Text or regex search across note content (optional)
   • query_type - Search type: "text" (default) or "regex"
   • search_in_path - Limit search to specific folder path
   • title_contains - Filter by text in note titles (string, array, or JSON string)
   • title_match_mode - How to match mul

... View full README on GitHub