obsidian

The Obsidian MCP Server provides programmatic access to an Obsidian vault through the Local REST API plugin. It exposes a set of MCP commands for vault management, search, and interaction with Obsidian UI commands. Through the MCP protocol, clients can authenticate using the Local REST API token, browse and manage files, perform content patches, execute Obsidian commands, and open files in the Obsidian UI. All communication is designed to be local and self-contained, making it suitable for automation, tooling, and integrations that need direct vault access without a GUI.

Once the server is running, you can connect a compatible MCP client via stdin/stdout. Use the available tools to list vault files, read and modify content, search with simple or advanced queries, and execute Obsidian commands. The toolset includes file management (get, create, update, patch, delete), content patching relative to headings or frontmatter, robust search capabilities (including Dataview DQL and JsonLogic), and command/navigation actions (list, execute, open). Ensure you provide the Obsidian Local REST API token for authentication to enable secure access to your vault.

Prerequisites:

• Obsidian with the Local REST API plugin installed and enabled
• Go 1.22+ (for building from source)
• Optional: Nix (for development environment)

Installation options:

From Docker (recommended for quick start):

1. Ensure Docker is installed and running.
2. Pull or build the Docker image for the Obsidian MCP Server from your registry:
   • docker pull obsidian-mcp-server-image
   • or build your own image from a Dockerfile if provided by the project maintainer.
3. Run the container (provide your API token via environment or config):
   • docker run -i -e OBSIDIAN_API_TOKEN=your-token obsidian-mcp-server-image

From Source (Go-based build):

1. Install Go 1.22+.
2. Clone the repository: git clone https://github.com/obsidian-mcp-server/obsidian-mcp-server.git
3. Build the binary: cd obsidian-mcp-server make build
4. Run the binary (example): ./bin/obsidian-mcp-server

Environment setup (required for authentication):

• OBSIDIAN_API_TOKEN: Your Obsidian Local REST API token. Provide this token to the server for authenticated access.
• If you run via Docker, pass the token as an environment variable or via a config file as appropriate for your image.

Post-install validation:

• Start the server and verify it is listening locally.
• Use a MCP client to connect and issue basic commands like get_server_info and list_vault_files to confirm connectivity.

Tips and common issues:

• Ensure the Obsidian Local REST API token is current and has read/write permissions for the vault.
• When using Docker, make sure the container has access to the host's Obsidian vault if needed, or mount the vault path into the container as a volume.
• The MCP protocol communicates via stdin/stdout; ensure your client handles these streams correctly and respects the token-based authentication flow.
• If you encounter connection errors, check that the Local REST API plugin is running in Obsidian and that the default URL (http://127.0.0.1:27123) is reachable from the MCP server environment.
• For patch_file_content and patch-like operations, provide precise targeting (headings, blocks, or frontmatter) to avoid unintended edits.
• When using search, tune context length to balance result relevance and payload size.