playbooks

home / mcp / obsidian mcp server

Obsidian MCP Server

Obsidian Knowledge-Management MCP (Model Context Protocol) server that enables AI agents and development tools to interact with an Obsidian vault. It provides a comprehensive suite of tools for reading, writing, searching, and managing notes, tags, and frontmatter, acting as a bridge to the Obsidian Local REST API plugin.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "cyanheads-obsidian-mcp-server": {
      "command": "npx",
      "args": [
        "obsidian-mcp-server"
      ],
      "env": {
        "MCP_AUTH_MODE": "jwt",
        "MCP_HTTP_HOST": "127.0.0.1",
        "MCP_HTTP_PORT": "3010",
        "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_ALLOWED_ORIGINS": "https://example.com,https://sub.example.com",
        "MCP_AUTH_SECRET_KEY": "YOUR_SECRET_KEY_32+_CHARS",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

You can empower AI agents and development tools to work directly with your Obsidian vault through an MCP server. This server exposes Obsidian functionality as MCP tools, enabling read, write, search, and management operations on your notes in a secure, scalable way. Use it to integrate Obsidian into AI workflows, IDE extensions, or external applications that need structured access to your vault.

How to use

Install the Obsidian MCP Server and connect it to your Obsidian vault so your AI agents can read, write, and manage notes through MCP tools.

You interact with the server by configuring an MCP client to run the server locally via stdio or remotely via HTTP. The server exposes a set of Obsidian tools that perform vault operations such as reading notes, updating content, searching, listing directories, and managing frontmatter and tags.

Use the provided environment variables to securely connect to the Obsidian Local REST API plugin, control caching behavior, and select the transport type. Ensure the Obsidian API key and base URL match your local Obsidian setup.

How to install

Prerequisites you must have before running the server.

  • Obsidian installed with the Local REST API plugin enabled
  • API key configured in the Obsidian plugin settings
  • Node.js installed (v18 or later recommended)
  • npm installed

Step-by-step setup and run flow.

1) Install dependencies and build the server if you are cloning from source.

2) Start the server using npm scripts or the local build output.

3) Point your MCP client to the server using the appropriate command and environment variables.

Configuration and usage notes

Key configuration enables secure communication with the Obsidian vault and performance improvements via an in-memory cache.

Environment variables control the connection to Obsidian, transport type, and cache settings.

The server supports two transport methods: stdio for local, high-control usage and http for remote integration.

Tools overview

The Obsidian MCP Server provides a suite of tools to interact with your vault. Each tool performs a specific operation on notes and vault metadata.

obsidian_read_note
obsidian_update_note
obsidian_search_replace
obsidian_global_search
obsidian_list_notes
obsidian_manage_frontmatter
obsidian_manage_tags
obsidian_delete_note

Security and safety considerations

Use HTTPS in production and enable proper TLS verification where possible. Configure strong API keys and limit client permissions. The server includes safeguards for path case-insensitive fallbacks and explicit modification modes to avoid unintended data loss.

Troubleshooting and support

If you encounter connectivity or authentication issues, verify the Obsidian API key and base URL, confirm the Obsidian Local REST API plugin is running, and check that the cache is enabled if you rely on cached search results.

Examples and quick start

To connect a client, configure the environment with your Obsidian API key and base URL. Use the recommended non-encrypted HTTP URL for simplicity during initial setup.

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available tools

obsidian_read_note

Retrieves the content and metadata of a specified note. Returns content in markdown or json format, supports case-insensitive path fallback, and includes file stats.

obsidian_update_note

Modifies notes using append, prepend, or overwrite operations. Can create files if they do not exist and target by path, active note, or periodic note.

obsidian_search_replace

Performs search-and-replace within a target note with support for string or regex search and options for case sensitivity, whole word matching, and replacing all occurrences.

obsidian_global_search

Performs a vault-wide search with text or regex support. Can filter by path and modification date and supports pagination.

obsidian_list_notes

Lists notes and subdirectories within a vault folder, with filters for extension and name patterns and a formatted tree view.

obsidian_manage_frontmatter

Atomically manages a note's YAML frontmatter with get, set, or delete operations without rewriting the entire file.

obsidian_manage_tags

Adds, removes, or lists tags for a note, handling both YAML frontmatter and inline tags.

obsidian_delete_note

Permanently deletes a specified note from the vault with safety fallbacks.