Obsidian

This Model Context Protocol (MCP) server lets AI models interact with Obsidian vaults, enabling you to manage notes, search content, and update metadata through a secure, configurable tool interface. It integrates directly with Obsidian via the Local REST API and provides a structured way for AI agents to perform file operations, search, and property management inside your vaults.

How to use

Install and run the Obsidian MCP Server, then connect your MCP client to the running process. Use the available tool endpoints to list vault contents, read and update note frontmatter, perform full-text searches, and run Obsidian commands. All actions are performed over a secured API channel with rate limiting and SSL options. You can combine file operations, searches, and property management to automate knowledge-base workflows inside Obsidian.

How to install

Prerequisites: Node.js (LTS recommended) and the Obsidian Local REST API plugin enabled.

# Option 1: Install from source
git clone git@github.com:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build

# Option 2: Install from npm
npm install obsidian-mcp-server

Run the server via the runtime command described in the configuration snippet below, and ensure the Obsidian Local REST API is accessible from the host where you run the MCP server.

Configuration and usage

Configure the MCP client to connect to the Obsidian MCP Server using a local stdio-based runtime. The following configuration snippet shows how to start the server process and supply necessary environment variables for authentication, protocol, timeouts, and rate limiting.

{
  "mcpServers": {
    "obsidian_mcp": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/build/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

SSL and security setup

Configure SSL verification and certificates to ensure secure communication between the MCP server and your Obsidian instance. The setup differs by operating system and deployment mode.

Windows development setup (not recommended for production): set VERIFY_SSL to "false", set OBSIDIAN_PROTOCOL to "http", and enable the Non-encrypted (HTTP) Server option in Obsidian's Local REST API settings.

Windows production setup: set VERIFY_SSL to "true" and install the Obsidian certificate as trusted root. Open Windows Certificate Manager (certmgr.msc), navigate to Trusted Root Certification Authorities > Certificates, import the certificate from Obsidian Settings > Local REST API > How to Access.

macOS: add the certificate to Keychain Access. Linux: install the certificate into ca-certificates and update system trust.

Error handling and limits

All errors include a five-digit code. HTTP status codes are mapped to MCP error codes, with a default server error of 50000. In development, detailed error messages include original stack traces.

Notes on security and best practices

Use strong API keys from Obsidian's Local REST API plugin, enable SSL, and configure rate limiting to protect your vault. Validate inputs and monitor performance to prevent abuse or unintended file modifications.

Available tools

obsidian_list_files_in_vault

List all vault contents, returning a structured view of folders and files at the vault root.

obsidian_list_files_in_dir

List contents of a directory relative to the vault root, returning files and subdirectories.

obsidian_get_file_contents

Get the textual contents of a file specified by a path relative to the vault root.

obsidian_find_in_file

Perform a text search within a file with optional context length to return surrounding content.

obsidian_complex_search

Execute advanced searches using JsonLogic to filter by tags, frontmatter, path patterns, or other metadata.

obsidian_append_content

Append new content to an existing file without replacing existing data.

obsidian_patch_content

Replace the entire content of a file with new content.

obsidian_list_commands

List available Obsidian commands that can be executed via the MCP interface.

obsidian_execute_command

Execute a specific Obsidian command by its command ID.

obsidian_open_file

Open a file in Obsidian, optionally in a new leaf.

obsidian_get_active_file

Get the currently active note content in Obsidian.

obsidian_get_periodic_note

Retrieve the content of periodic notes (daily, weekly, monthly, etc.).

obsidian_get_tags

Fetch all tags from the vault, optionally scoped to a directory.

obsidian_get_properties

Read the YAML frontmatter properties of a note.

obsidian_update_properties

Update note properties such as title, author, type, tags, and other metadata; timestamps managed automatically.