mcp-obsidian

MCP-Obsidian acts as a universal bridge between any MCP-compatible AI assistant and your Obsidian vault. It exposes a comprehensive set of vault operations through the MCP protocol, including reading and writing notes, listing directories, searching notes with BM25 ranking, and managing metadata and tags. This enables AI tools like Claude Desktop, Claude Code, ChatGPT Desktop, and other MCP-enabled assistants to interact with your vault safely—read-only when needed, with explicit write modes (overwrite, append, prepend) for editing notes, and protections to prevent YAML frontmatter corruption. To get started, run the server locally with your vault path and point your AI client to the generated MCP server endpoint via the provided command configuration. The toolkit supports 14 methods covering file, directory, batch, and metadata operations, along with error handling and token-optimized responses for efficient usage.

Once the server is running, configure your AI client by providing an MCP server entry that specifies the command to launch the MCP-Obsidian server and the vault path. For example, using npx, you can reference the latest release of the MCP-Obsidian package and pass your vault path as an argument. You can also configure multiple vaults under different MCP server aliases for organization, such as obsidian-personal and obsidian-work, each with its own vault path. After configuration, you can issue natural language requests to your AI client like: "List files in my Obsidian vault", "Read my note called 'project-ideas.md'", or "Create a new note with today's date". The server will translate these requests into MCP-formatted operations and return structured results.

Prerequisites:

• Node.js v18.0.0 or later installed on your system
• An Obsidian vault (local directory with .md files)
• An MCP-compatible AI client (e.g., Claude Desktop, Claude Code, ChatGPT Desktop, etc.)

Installation steps (End users):

1. Install Node.js from https://nodejs.org if you haven't already.

2. Run the MCP-Obsidian server directly without a local install:

   npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault
   

3. Take note of the command and the path you passed (this is the MCP server endpoint to use in your AI client).

Installation steps (Developers):

1. Clone the repository for development.

2. Use the correct Node.js version specified by the project (e.g., via .nvmrc).

3. Install dependencies:

   npm install
   

4. Test locally with MCP inspector:

   npx @modelcontextprotocol/inspector npm start /path/to/your/vault
   

5. Optional: test using the global inspector CLI if desired:

   npm install -g @modelcontextprotocol/inspector
   mcp-inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault
   

Running the server (quick start):

npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault

If you want to run via npm script during development, you can use:

npm start /path/to/your/obsidian/vault

Notes and tips:

• You can configure multiple vaults by creating separate MCP server entries (aliases) each pointing to a different vault path.
• The server performs safe frontmatter parsing and validation using gray-matter and excludes system directories like .obsidian from path listings.
• When writing notes, use the available write modes (overwrite, append, prepend) to control content changes.
• For AI clients, you typically provide a configuration JSON with mcpServers containing the server alias, command (npx in this case), and the vault path as arguments.
• Ensure your vault permissions allow reading/writing as your use-case requires. Be mindful of YAML frontmatter and metadata to avoid unintended edits.
• By default, the examples use npx to invoke the server; you can adapt to other integration patterns as needed (e.g., different aliases, multiple vaults).
• The MCP toolkit includes 14 vault operations (read_note, write_note, patch_note, delete_note, move_note, move_file, list_directory, read_multiple_notes, search_notes, get_frontmatter, update_frontmatter, get_notes_info, get_vault_stats, manage_tags) for comprehensive control.