If you keep a second brain in Obsidian, you have probably wished your AI assistant could read it. The obsidian mcp server makes that possible. By connecting Claude Desktop to your local vault, you can ask questions, search across thousands of notes, append new content, and edit existing files, all without leaving your AI chat interface. For knowledge workers, researchers, and developers who live inside Obsidian, this is the integration that ties your personal knowledge base to the growing ecosystem of AI tooling built on the Model Context Protocol.
The main server is mcp-obsidian by MarkusPfundstein (GitHub: MarkusPfundstein/mcp-obsidian). It is Python-based, distributed via uvx, and exposes seven core tools that cover the most common vault operations. Setup takes under ten minutes if you know where to look.
Prerequisites
Before installing mcp-obsidian, two things need to be in place.
Obsidian must be installed and running with a vault you want to connect. The vault can live anywhere on your local machine. The obsidian mcp server does not touch cloud-synced vaults directly; it always goes through Obsidian's own file handling.
The Obsidian Local REST API community plugin is the second requirement, and it is non-negotiable. This plugin is what opens Obsidian's file system to external programs. Once enabled, it starts a lightweight HTTP server on localhost (default port 27124) and generates an API key you can copy from its settings panel. That key is what authenticates the MCP server's requests.
To install the plugin:
- Open Obsidian and go to Settings > Community Plugins.
- Disable safe mode if prompted.
- Search for Local REST API, install it, and enable it.
- Open the plugin settings and copy the API Key. Keep it handy for the next step.
One important constraint: the Local REST API server only runs while Obsidian is open. If you close Obsidian, the MCP server loses its connection and every tool call will fail. Plan to keep Obsidian running in the background during any AI session where you want vault access.
Installation and Claude Desktop Configuration
The mcp-obsidian package is distributed via uvx, which means you do not need to clone a repository or manage a Python virtualenv manually. You do need uv installed. If you do not have it yet, install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh
Once uv is available, open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add or merge the following block into the mcpServers object:
{
"mcpServers": {
"mcp-obsidian": {
"command": "uvx",
"args": ["mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "<your_api_key>",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}
Replace <your_api_key> with the key you copied from the Local REST API plugin settings. Leave OBSIDIAN_HOST and OBSIDIAN_PORT at their defaults unless you have changed the plugin's listening address.
Save the file and fully restart Claude Desktop (quit and reopen, not just close the window). After restart, the mcp-obsidian server should appear as an available tool source. You can verify by asking Claude: "List the files in my vault root." If it returns file paths, the connection is working.
Compatible MCP Clients
mcp-obsidian follows the standard MCP server pattern, so it works with any MCP-compatible client. Claude Desktop is the primary supported client and the one most documentation is written around. Other clients handle configuration slightly differently.
| Client | Compatible | Configuration Location |
|---|---|---|
| Claude Desktop | Yes | claude_desktop_config.json |
| Cursor | Yes | ~/.cursor/mcp.json |
| VS Code (Continue extension) | Yes | settings.json MCP block |
| Cline | Yes | MCP tab in extension settings |
| Zed | Partial | Beta MCP support, some instability |
| Windsurf | Yes | MCP settings panel |
| ChatGPT | No | Uses GPT Actions, not MCP protocol |
If you are using a client other than Claude Desktop, the JSON configuration block is identical; only the file location changes.
Tools the Server Exposes
Once connected, mcp-obsidian gives Claude Desktop access to seven tools that cover the core read, write, and search operations across your vault.
list_files_in_vault returns every file and directory in your vault. This is the orientation tool. Claude can use it to understand your folder structure before navigating to specific content.
list_files_in_dir is a scoped version of the above. Pass a folder path and get only that directory's contents. Useful when your vault has hundreds of notes and you want Claude to focus on one area.
get_file_contents reads the full markdown content of any note by file path. Claude receives the raw text and can then summarize, quote, compare, or reason about it in any way you ask.
search runs full-text search across the entire vault. Submit a query string and the tool returns matching file paths along with excerpts showing where the term appears. This is how you find notes when you do not know the exact file name.
patch_content makes surgical edits by targeting a specific heading or block reference inside a note. Claude can rewrite a section without touching the rest of the document. This is the most powerful write tool in the set because it preserves structure.
append_content adds new content to the end of an existing note. The primary use cases are logging, journaling, and accumulating research notes from a conversation into a permanent record.
delete_file removes a note from the vault permanently. There is no built-in undo through the MCP layer, so treat this tool with care and consider keeping Obsidian's own trash or sync history active as a safety net.
Quality Assessment
The mcp-obsidian server sits in the middle of the quality range for community MCP servers. It does what it says: the core read, search, and write operations work reliably when the Local REST API plugin is running and Obsidian is open. For most personal productivity use cases, the seven available tools cover the realistic scope of what you would want an AI to do with your notes.
The main limitation is the Obsidian dependency. Every tool call passes through the Local REST API plugin, which means the server is only operational when Obsidian is actively running. This is a constraint of the underlying plugin architecture, not a flaw in mcp-obsidian specifically, but it does mean the integration is not suitable for any workflow that requires background or scheduled vault access.
Documentation is functional but minimal. The README covers installation and the available tools, but edge cases like multi-vault setups or non-default plugin ports require some experimentation. Maintenance has been steady rather than active.
You can find this server's listing, quality grade, and community annotations on MCPVault. The grade reflects documentation quality, maintenance history, and reliability reports collected from real-world usage. If you are evaluating this server for a team deployment and want to see how it compares to alternatives in the same category, the vault's filtering tools make that comparison straightforward.
Alternatives Worth Knowing
If the standard mcp-obsidian setup does not cover your workflow, two alternatives offer expanded capabilities.
cyanheads/obsidian-mcp-server is TypeScript-based and exposes over 14 tools, including more granular property management, frontmatter access, and additional metadata operations. It is considered the more feature-complete option for power users who need fine-grained control. As of 2026, it is also more actively maintained than the original Python implementation.
jacksteamdev/obsidian-mcp-tools takes a different architectural approach by running MCP tooling as an Obsidian plugin rather than as an external server. This enables semantic search through integration with the Smart Search plugin, which goes beyond the keyword matching available in the search tool exposed by mcp-obsidian. The tradeoff is added setup complexity and a tighter coupling to specific plugin combinations.
Start with mcp-obsidian. If you hit its limits, evaluate the cyanheads server next.
Frequently Asked Questions
Does mcp-obsidian work if Obsidian is closed?
No. The server relies on the Obsidian Local REST API plugin, which only runs while Obsidian is open. If you close Obsidian and attempt a tool call through Claude Desktop, you will receive a connection refused error. Keep Obsidian running in the background whenever you plan to use this integration. Some users set Obsidian to launch at login and minimize it to the system tray for a seamless experience.
Is my vault content sent to Anthropic or any cloud service?
Your note content is read locally by the MCP server and included in tool call responses that Claude Desktop sends to Anthropic's API for processing. This means note content that Claude retrieves does travel to Anthropic's servers as part of the conversation context. Anthropic's standard API data handling policies apply. If your vault contains confidential information, review those policies before connecting the integration, and consider whether you want to scope the vault to a subset of less sensitive notes rather than your entire knowledge base.
Can Claude write new notes, not just edit existing ones?
Yes, with a minor workaround. The server does not expose a dedicated "create file" tool, but you can use append_content with a file path that does not yet exist. The Local REST API plugin will create the file if the target path is missing. Alternatively, patch_content can initialize a note by targeting a heading that does not exist yet, which causes the plugin to create both the file and the heading. Neither approach is as clean as an explicit create tool, but both work reliably in practice.
What is the difference between mcp-obsidian and cyanheads/obsidian-mcp-server?
mcp-obsidian is the simpler, more widely referenced implementation. Seven tools, Python-based, minimal configuration. It is the right starting point for most users. cyanheads/obsidian-mcp-server is TypeScript-based, exposes more than 14 tools, and provides more granular access to note metadata and frontmatter properties. The cyanheads server also tends to see more frequent updates. If you find yourself wanting capabilities that mcp-obsidian does not expose, switching to the cyanheads implementation is the recommended upgrade path. The configuration format is similar enough that migration is straightforward.
Get Started with MCPVault
The obsidian mcp server is one of hundreds of community-built integrations catalogued in the vault. Browse the full server directory at /servers to find tools for your other applications and workflows. Every listing includes a quality grade, a compatibility summary, and community annotations so you can evaluate a server before committing to the setup.
If you maintain or have built an MCP server, you can claim your listing and add verified documentation at /claim. Claimed servers receive a verified badge and access to the annotation tools that help your users get started faster.
Next steps:
- Browse all MCP servers and filter by category, client, or quality grade
- Understand MCPVault quality grades and what each tier means
- Learn about the verified badge and how to claim your server listing