Obsidian Local REST API MCP server for AI agents

The Obsidian MCP Server transforms your Obsidian vault into a knowledge base accessible to AI agents through the Model Context Protocol (MCP). This server enables sophisticated search and retrieval operations across your notes, allowing AI to perform complex knowledge discovery tasks that would take hours to do manually.

Installation

Prerequisites

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

Installing from PyPI

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

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

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

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

Running the Server

Start the MCP server with:

obsidian-mcp

Available Tools

The server provides three main tools:

Search Vault

The search_vault tool offers advanced search capabilities with flexible filters:

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
title_match_mode - How to match multiple terms: "any" (OR) or "all" (AND)
tag - Filter by tag (searches frontmatter and inline #tags)
tag_match_mode - How to match multiple tags: "any" (OR) or "all" (AND)
context_length - Amount of content to return
include_content - Boolean to retrieve complete content of all matching notes
created_since/until - Filter by creation date
modified_since/until - Filter by modification date
page_size - Results per page
max_matches_per_file - Limit matches per note

Get Note Content

The get_note_content tool retrieves complete content and metadata of a specific note by path.

Browse Vault Structure

The browse_vault_structure tool navigates vault directory structure:

path - Directory to browse (defaults to vault root)
include_files - Boolean to include files (default: False, folders only for speed)
recursive - Boolean to browse all nested directories

Usage Examples

Basic Searches

# Find notes by title in a specific folder
search_vault(
  search_in_path="Work/Projects/",
  title_contains="meeting"
)

# Find notes with multiple title terms (OR logic)
search_vault(
  title_contains=["foo", "bar", "fizz", "buzz"],
  title_match_mode="any"  # Default
)

# Find notes with ALL title terms (AND logic)
search_vault(
  title_contains=["project", "2024"],
  title_match_mode="all"
)

# Get all recent notes with full content
search_vault(
  modified_since="2025-05-20",
  include_content=True
)

# Text search with context
search_vault(
  query="API documentation",
  search_in_path="Engineering/",
  context_length=500
)

# Search by tag
search_vault(
  tag="project"
)

# Regex search for OR conditions
search_vault(
  query="foo|bar",
  query_type="regex",
  search_in_path="Projects/"
)

Advanced Multi-Step Workflows

# Strategic Project Analysis:
# Step 1: Get all project documentation
search_vault(
  search_in_path="Projects/Infrastructure/",
  title_contains=["planning", "requirements", "architecture"],
  title_match_mode="any",
  include_content=True
)

# Step 2: Find related technical discussions
search_vault(
  tag=["infrastructure", "technical-debt"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

# Meeting Action Item Mining:
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

# Vault Structure Exploration:
browse_vault_structure(recursive=True)

# Deep dive into specific areas
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

# Tag-Based Knowledge Mapping:
# Find notes with multiple tags (AND logic)
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# Find notes with any relevant tags (OR logic)
search_vault(
  tag=["architecture", "design", "implementation"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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. Restart Claude Desktop for the changes to take effect