obsidian-api

This Obsidian MCP Server exposes powerful vault search and retrieval capabilities to AI agents via the Local REST API plugin. It provides three main tools: search_vault for advanced, filterable searches with optional full-content retrieval or regex-based queries; get_note_content to fetch a single note's complete content and metadata; and browse_vault_structure to navigate the vault directory tree. You can combine these tools to perform multi-step knowledge tasks, such as locating relevant notes, validating completeness, and aggregating content with source references. The server is designed to work smoothly with agents that can construct complex query payloads, apply content filters, and parse the returned data for downstream reasoning. The included environment variables allow you to point the server at your Obsidian API endpoint and supply authentication if your setup requires it. For secure local usage, consider keeping your API key in environment management tooling rather than hardcoding it in scripts.

Prerequisites

• Obsidian Local REST API plugin installed in your Obsidian vault and enabled
• Access to a Python environment with pip, or the uv tool for running Python packages
• Optional: a JavaScript/Node environment if you prefer alternative runtimes (not required for this server)

Installation steps

1. Install from PyPI (Recommended)

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

# Or with uv for faster local development
uv pip install obsidian-api-mcp-server

2. Add to MCP Configuration (example shown in README)

{
  "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"
      }
    }
  }
}

3. 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 .

4. Run the MCP server

obsidian-mcp

Environment variables:

• OBSIDIAN_API_URL: URL to your Obsidian Local REST API (HTTPS by default). Default shown in docs is https://localhost:27124.
• OBSIDIAN_API_KEY: Optional API key if you’ve configured authentication on the Obsidian API. Do not hardcode in scripts; use a .env file or environment management.

Security: The server and Obsidian API may use self-signed certificates for local HTTPS. If you encounter SSL issues, you can set OBSIDIAN_API_URL to http://localhost:27123 for non-SSL testing, or configure your environment to trust the self-signed certificate.

Tips:

• When using search_vault without a query, the server can return full content for filter-only searches if include_content is true.
• regex and complex filters are supported in query_type and related fields to enable advanced querying.
• Keep your Obsidian vault path and API endpoint stable to avoid connection drops during long multi-step workflows.