home / mcp / obsidian mcp server

Obsidian MCP Server

Provides an Obsidian MCP server that integrates with the Obsidian Local REST API to read, create, and edit notes.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "derrikjb-obsidian_mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "DEBUG": "false",
        "MCP_PORT": "3000",
        "MCP_TRANSPORT": "stdio",
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

You can run an Obsidian MCP Server to interact directly with your Obsidian vaults from MCP clients. It connects to the Obsidian Local REST API to read, create, and edit notes, enabling seamless note management across tools and interfaces.

How to use

To use the Obsidian MCP Server, configure a client to connect via HTTP or run the local stdio version for desktop integrations. The HTTP mode exposes a single MCP endpoint over HTTP, while the stdio mode runs locally and communicates through a standard input/output stream. After connecting, you can read file contents, create or update notes, search across your vault, and perform directory operations to inspect vault structure.

How to install

Prerequisites you need before installation:

Node.js v18 or higher

Obsidian with Local REST API plugin enabled

A valid Obsidian API key from the Local REST API settings

Step-by-step installation and setup steps you should follow exactly as shown below.

npm install
npm run build
npm run setup

Additional sections

Configuration and startup flow you will follow after installation includes choosing a transport mode, providing your Obsidian API key, and starting the server in your preferred mode. You can run the HTTP mode for Open WebUI or the stdio mode for Claude Desktop integration. The server will verify the Obsidian REST API connection on startup and print a startup health check with plugin and Obsidian versions.

Notes on security and operation include guarding your API key, ensuring Obsidian is running with the Local REST API plugin, and starting the server with the appropriate environment variables when using the stdio configuration.

Configuration

You can configure the server either through a guided setup wizard or manually by editing environment variables. The setup wizard collects your Obsidian API key, transport mode, and optional settings. Manual configuration involves copying the environment template and adjusting values.

npm run setup

# or manual configuration
cp .env.example .env
# then edit .env to set OBSIDIAN_API_URL, OBSIDIAN_API_KEY, MCP_TRANSPORT, MCP_PORT, etc.

Troubleshooting

If you encounter issues with the Open WebUI connection or general startup problems, verify that the server is running, check the MCP endpoint URL, and review the debug logs if you enabled debug mode.

Common steps include checking the health endpoint, ensuring the Obsidian API URL and API key are correct, and re-running the setup if needed.

Tools and capabilities

The server exposes a set of tools to interact with your Obsidian vault. Key operations include vault file handling, directory listing, and search functionality.

Available tools

vault_get_file

Get file content with optional format: markdown (default), json, or document-map.

vault_create_file

Create or completely replace a file in the vault.

vault_append_to_file

Append content to an existing or new file.

vault_patch_file

Partially update a file, supporting operations like append, prepend, or replace on headings, blocks, or frontmatter.

vault_delete_file

Delete a file from the vault.

vault_list

List files and directories in the vault.

search_simple

Simple text search with context.

search_advanced

Advanced search using Dataview DQL or JsonLogic.