obsidian

The Obsidian MCP Server provides a set of tools to interact with an Obsidian vault via the MCP protocol. It supports vault operations such as listing, reading, creating, updating, and deleting notes, along with tag management and link navigation. The server can run in two transports: a local stdio mode for direct use and a remote HTTP mode for network access. To get started, ensure your Obsidian vault path is correctly set via OBSIDIAN_VAULT_PATH. Then start the server in stdio mode or HTTP mode depending on your workflow. You can connect with MCP clients like Claude Desktop, Cursor, Windsurf, or VS Code to use the provided tools.

Key tools include note operations (obsidian_list_notes, obsidian_read_note, obsidian_write_note, obsidian_delete_note, obsidian_search_notes), vault information tools (obsidian_vault_stats, obsidian_list_tags, obsidian_get_tagged_notes), and link navigation tools (obsidian_get_links, obsidian_get_backlinks). Tools return data in JSON by default or can be rendered as Markdown if you request response_format=markdown. Use the tools to paginate results, filter by folder, or search by content, tags, or metadata.

Prerequisites

• Node.js (and npm) installed on your machine
• Access to a path where you want to mount your Obsidian vault

Installation steps

1. Install dependencies and build the server

npm install
npm run build

2. Prepare the environment

• Ensure OBSIDIAN_VAULT_PATH points to your Obsidian vault directory Optional: set TRANSPORT to http for HTTP mode and adjust HOST/PORT as needed

3. Run in stdio mode (local integration)

export OBSIDIAN_VAULT_PATH=/path/to/your/vault
npm start

4. Run in HTTP mode (remote access)

export OBSIDIAN_VAULT_PATH=/path/to/your/vault
export TRANSPORT=http
export PORT=3000
npm run start:http

5. Optional: verify the server is responding via the MCP endpoint (default /mcp) with a client command or curl

Environment variables

• OBSIDIAN_VAULT_PATH: required. Absolute path to the Obsidian vault.
• TRANSPORT: optional. stdio or http. Default is stdio.
• PORT: optional. HTTP server port (default 3000).
• HOST: optional. HTTP server host (default 127.0.0.1). Common issues
• Ensure the vault path is accessible by the running process; permissions errors are common when the path is invalid.
• When using HTTP transport, ensure the specified port is open and not blocked by a firewall.
• If you update the vault contents externally, consider refreshing or re-reading to keep client state consistent. Configuration tips
• Use obsidian_list_notes with folder filters to limit results for large vaults.
• Use obsidian_get_links and obsidian_get_backlinks to explore note relationships for better navigation.
• For large note sets, rely on pagination provided by list_notes tools to avoid excessive payloads.