obsidian

The Obsidian MCP Server exposes a set of Obsidian-focused MCP tools that allow automated agents to read, modify, and query your Obsidian vault through the Obsidian Local REST API plugin. Tools include reading notes with metadata, updating notes (append, prepend, or overwrite), performing search and replace within notes, executing global vault searches, listing note trees, and managing frontmatter and tags. By interfacing with these tools via MCP transport, AI agents can perform vault operations as part of complex workflows while benefiting from the server’s validation, error handling, and security features.

To use, run the server locally or in your environment with the required environment variables configured (see installation notes). Once running, MCP clients can invoke tools such as obsidian_read_note, obsidian_update_note, obsidian_search_replace, obsidian_global_search, obsidian_list_notes, obsidian_manage_frontmatter, obsidian_manage_tags, and obsidian_delete_note to perform vault operations. The server communicates with the Obsidian Local REST API plugin inside your vault, enabling safe and structured interactions instead of ad-hoc scripting. The included vault cache service helps keep responses fast and resilient, with fallbacks for the global search when the live API is unavailable.

Prerequisites

• Node.js (v18+ recommended) and npm or pnpm
• Access to an Obsidian vault with the Obsidian Local REST API plugin installed and configured
• A running Obsidian instance exposing the Local REST API (default port 1123/https as configured by the plugin, adjust OBSIDIAN_API_BASE_URL accordingly)

Install and run

1. Clone the repository or download the package for the Obsidian MCP Server.
2. Install dependencies (in the project root):
   • npm install
   • or yarn install
3. Configure environment variables. Create a .env file or export the following variables as appropriate:
   • PORT=3000
   • OBSERVATORY_VAULT_PATH=/path/to/your/obsidian/vault
   • OBSIDIAN_API_BASE_URL=http://localhost:1123
   • DOTENV_CONFIG_PATH=.env (if using dotenv)
4. Build the server (if the project uses a build step):
   • npm run build
5. Start the server:
   • npm run start The server will expose an MCP endpoint (e.g., http://localhost:3000/mcp) and register the Obsidan MCP server under the name obsidian.

Notes

• Ensure the Obsidian Local REST API plugin is installed and accessible from the server host.
• Adjust the Obsidian API base URL and vault path to your environment. The server expects the vault to be reachable and the API to be authenticated per your Obsidian Local REST API configuration.

Tips and common considerations:

• Environment variables are critical: specify the vault path and the Obsidian Local REST API URL accurately to avoid failures when tools attempt to read or modify notes.
• The vault cache service improves performance and resilience; if you notice stale results, check cache refresh settings or permissions.
• For safety, tools provide case-insensitive path fallbacks and explicit frontmatter/tag management to minimize unintended overwrites.
• If you enable authentication for the MCP HTTP layer (JWT/OAuth), ensure clients supply valid tokens; otherwise, operate in a trusted, isolated environment.
• Review the Obsidian tool docs in the repository to understand exact tool inputs, such as the required note paths, formatting options (markdown/json), and frontmatter keys when using manage_frontmatter or manage_tags.