Obsidian

You run an MCP server that securely exposes your Obsidian vaults to AI agents and MCP clients. It lets you read, write, search, and manage notes via the Obsidian Local REST API, with multi‑vault support, remote integrations, and robust tooling to integrate AI workflows into your notes ecosystem.

How to use

Start the server with a client that understands MCP. You can connect via HTTP for remote access or run a local (stdio) instance that the MCP client can import directly. Use the multi‑vault routing to target a specific vault by setting the vault parameter when invoking tools. The server ships with a rich set of Obsidian tools for reading files, updating content, performing global searches, managing frontmatter and tags, and querying Dataview and Tasks across your vaults. When you issue commands, you can specify the vault to operate on and receive structured results suitable for further automation or prompting.

How to install

Prerequisites you need to prepare before installation: Node.js (v18 or later recommended) and npm, Obsidian installed with the Local REST API Plugin enabled, and a configured API key from the Obsidian plugin settings. If you plan remote access, you may also install and configure Tailscale for secure connectivity.

Step by step install and run flow:

# 1) Clone the enhanced MCP server repo
git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
cd obsidian-mcp-server-enhanced

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

# 4) Start the HTTP server (default port 3010)
npm run start:http

Configuration

Configure your environment to tell the server how to connect to your Obsidian instances and how to authenticate clients. You can run in single‑vault mode or multi‑vault mode. Core environment variables include MCP_AUTH_KEY for client authentication and OBSIDIAN_VAULTS or OBSIDIAN_API_KEY/OBSIDIAN_BASE_URL for vault access. The stateless Claude.ai integration, TLS/SSL settings, and cache options are configurable as shown in the examples.

Multi‑vault and remote access notes

The server supports multiple Obsidian instances through a JSON vault configuration. Each vault has its own API key and base URL. Remote access can be secured with Tailscale Funnel, providing end‑to‑end encryption and automatic certificates without port forwarding. For Claude.ai Remote MCP integration, the server can operate in stateless HTTP mode or traditional session mode, with a dedicated MCP_AUTH_KEY used for authentication.

Security and monitoring

Security is handled via a dual authentication model: MCP_AUTH_KEY for server access and individual vault API keys for vault access. Enable the in‑memory vault cache to improve performance and resilience, with automatic background refresh and a fallback for global search. Enterprise features include health checks, auto‑restart, and logging with sensitive data redaction.

Notes and troubleshooting

If you encounter port conflicts, the server can manage ports in the 3010–3013 range and adjust automatically. Ensure your Obsidian Local REST API plugin is running on each vault with its own base URL and API key. When using remote Claude.ai or ChatGPT workflows, use the provided MCP_AUTH_KEY for authentication and point clients to the appropriate MCP HTTP URL or local stdio entry as configured.

Examples and workflows

Use the Obsidian tools to read, update, and search notes across vaults. For example, read a file from a specific vault, update a note with new content, or run a global text search, all through MCP tooling. For advanced automation, combine vault routing with Tasks and Dataview queries to generate summaries or dashboards that AI agents can consume.

Available tools

obsidian_read_file

Retrieves the content and metadata of a specified file, with optional formatting and stats.

obsidian_update_file

Modifies a note by appending, prepending, or overwriting content.

obsidian_search_replace

Performs search-and-replace within a target note with support for regex and options.

obsidian_global_search

Searches the entire vault with text or regex queries and supports paging.

obsidian_list_files

Lists files and subfolders with optional filters and a tree view.

obsidian_manage_frontmatter

Atomically get, set, or delete YAML frontmatter keys.

obsidian_manage_tags

Add, remove, or list tags in a note both in frontmatter and inline.

obsidian_delete_file

Permanently delete a file with optional case-insensitive path fallback.

obsidian_dataview_query

Execute Dataview DQL queries and generate reports.

obsidian_task_query

Query and analyze tasks across vaults with various filters.

obsidian_periodic_notes

Create and manage daily, weekly, monthly, or yearly notes.

obsidian_block_reference

Work with block references and heading operations.

obsidian_graph_analysis

Analyze note connections and vault relationships.

obsidian_template_system

Create files from templates with variable substitution.

obsidian_smart_linking

Get intelligent link suggestions and recommendations.