--- title: "Obsidian MCP Server: Let Claude Read and Write Your Vault" url: "https://mcpshelf.co/servers/obsidian" description: "The Obsidian MCP server lets Claude search, read and edit notes in your vault through the Local REST API plugin. Plugin setup, config and what it can delete." updated: "2026-10-27" site: "MCP Shelf" --- # Obsidian MCP > Search, read and edit the notes in your Obsidian vault. ## At a glance This server reaches your vault through the Local REST API community plugin, so Obsidian has to be open while you use it. The model can list folders, search across every note, read files, append text, and insert text under a particular heading, block or frontmatter field without rewriting the whole note. It can also delete files and folders. Keep the vault synced or backed up, and tell the assistant to use Obsidian at the start of a chat, because the author notes it then reaches for the tools reliably. | | | | --- | --- | | Made by | Markus Pfundstein, an independent developer | | GitHub | https://github.com/MarkusPfundstein/mcp-obsidian | | PyPI package | [mcp-obsidian](https://pypi.org/project/mcp-obsidian/) 0.2.3 (20 Aug 2026) | | GitHub stars | 4.5K | | Downloads | 5K a week | | Last commit | 31 Aug 2026 | | Tools | 15 | | Runs on | Your computer | | Install check | Started in our test | | Category | [Knowledge and work apps](https://mcpshelf.co/categories/knowledge-and-work) | **Our check:** We ran this exact config on 27 Oct 2026: it started and answered with 15 tools. The shared database gave "npx mcp-obsidian", an npm package by someone else. This project publishes mcp-obsidian on PyPI and runs with uvx. ## Tools We listed 15 tools on 27 Oct 2026. 0 only read; the rest can change things or run commands. | Tool | Kind | What it is for | | --- | --- | --- | | `obsidian_list_files_in_dir` | changes | Lists the files and folders inside one folder. | | `obsidian_list_files_in_vault` | changes | Lists the files and folders at the top of the vault. | | `obsidian_get_file_contents` | changes | Reads one note in full. | | `obsidian_simple_search` | changes | Finds notes that contain a piece of text, with the surrounding context. | | `obsidian_patch_content` | changes | Inserts or replaces text under a heading, at a block reference or in a frontmatter field. | | `obsidian_append_content` | changes | Adds text to the end of a note, creating it if it does not exist. | | `obsidian_put_content` | changes | Creates a note or replaces a whole note's text. The old text is gone. | | `obsidian_delete_file` | changes | Deletes a note or a folder. | | `obsidian_complex_search` | changes | Searches with a JsonLogic query, including glob and regular-expression matches on paths and content. | | `obsidian_search_by_tag` | changes | Finds every note with a tag, from frontmatter or inline #tags. | | `obsidian_get_frontmatter` | changes | Returns only a note's YAML frontmatter, which is lighter when you just need tags or dates. | | `obsidian_batch_get_file_contents` | changes | Reads several notes in one call, each under its own header. | | `obsidian_get_periodic_note` | changes | Opens the current daily, weekly, monthly, quarterly or yearly note. | | `obsidian_get_recent_periodic_notes` | changes | Lists the most recent periodic notes of one type. | | `obsidian_get_recent_changes` | changes | Lists the notes changed most recently. | ### How clearly it describes its tools 15 of 15 tools have a description and 0 of 15 say whether they change things. The tool list takes at least ~1,200 tokens of context. No tool says whether it only reads or can change things, so your client treats them all alike: keep approvals on. ## Set it up 1. In Obsidian, open Settings → Community plugins, install Local REST API and enable it. 2. Copy the API key from the plugin's settings into OBSIDIAN_API_KEY. 3. Keep Obsidian open while you use the server. ### Claude Desktop Where: claude_desktop_config.json (Settings → Developer → Edit Config) ```json { "mcpServers": { "obsidian": { "command": "uvx", "args": [ "mcp-obsidian" ], "env": { "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY", "OBSIDIAN_HOST": "127.0.0.1", "OBSIDIAN_PORT": "27124" } } } } ``` ### Claude Code Where: Your terminal, in the project folder ```bash claude mcp add-json obsidian '{"command":"uvx","args":["mcp-obsidian"],"env":{"OBSIDIAN_API_KEY":"YOUR_LOCAL_REST_API_KEY","OBSIDIAN_HOST":"127.0.0.1","OBSIDIAN_PORT":"27124"}}' ``` ### Cursor Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project ```json { "mcpServers": { "obsidian": { "command": "uvx", "args": [ "mcp-obsidian" ], "env": { "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY", "OBSIDIAN_HOST": "127.0.0.1", "OBSIDIAN_PORT": "27124" } } } } ``` ### VS Code Where: .vscode/mcp.json in your project ```json { "servers": { "obsidian": { "type": "stdio", "command": "uvx", "args": [ "mcp-obsidian" ], "env": { "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY", "OBSIDIAN_HOST": "127.0.0.1", "OBSIDIAN_PORT": "27124" } } } } ``` ### Windsurf Where: ~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "obsidian": { "command": "uvx", "args": [ "mcp-obsidian" ], "env": { "OBSIDIAN_API_KEY": "YOUR_LOCAL_REST_API_KEY", "OBSIDIAN_HOST": "127.0.0.1", "OBSIDIAN_PORT": "27124" } } } } ``` ### ChatGPT Where: Not supported ChatGPT only connects to remote servers by URL. This one runs on your computer, so use Claude, Cursor or VS Code. ## Settings | Setting | Kind | Required | What it does | | --- | --- | --- | --- | | `OBSIDIAN_API_KEY` | env | yes | The key shown in the Local REST API plugin's settings. | | `OBSIDIAN_HOST` | env | no | Where Obsidian is running. Defaults to 127.0.0.1; use host.docker.internal when the server runs in Docker. Example: `127.0.0.1` | | `OBSIDIAN_PORT` | env | no | The plugin's HTTPS port. Defaults to 27124. Example: `27124` | ## What it can touch **It can read** - Every note and folder in the vault Obsidian has open **It can change** - Notes it appends to, patches or overwrites - Notes and folders it deletes **Safer setup:** Keep the vault under sync or version control so changes can be undone, and ask the model to append or patch rather than overwrite. ## Before you start - Obsidian with the Local REST API community plugin enabled - The API key from that plugin - uv (Python 3.11 or newer) ## Good for - Summarising meeting notes and saving the summary as a new note - Finding every note that mentions a project or a person - Appending tasks or log entries to a running note ## If it does not work **Every call fails to connect** Obsidian must be open with the Local REST API plugin enabled. Check the port in the plugin's settings matches OBSIDIAN_PORT. **Claude Desktop cannot find uvx** Run which uvx and put the full path in the command field. **The model answers from memory instead of the vault** Say at the start of the chat that it should use Obsidian; after that it calls the tools reliably. **It fails to start after installing other Python packages** It needs version 1 of the MCP Python library. uvx keeps its own environment, so start it with uvx rather than pip. ## Similar servers | Server | Tools | Runs on | Stars | | --- | --- | --- | --- | | [Google Workspace MCP](https://mcpshelf.co/servers/google-workspace) | 43 | Your computer | 3.4K | | [12306 MCP](https://mcpshelf.co/servers/12306) | 8 | Your computer | 2.4K | | [Google Search Console MCP](https://mcpshelf.co/servers/search-console) | 21 | Your computer | 2K | | [Telegram MCP](https://mcpshelf.co/servers/telegram) | 147 | Your computer | 1.9K | ## Questions ### Is this made by Obsidian? No. It is an independent project that talks to the community Local REST API plugin. ### Does it work with an Obsidian Sync or iCloud vault? Yes. It works on whatever vault is open in Obsidian on that machine, wherever the files live. ### Does it need Obsidian to be running? Yes. The plugin runs inside Obsidian, so the app has to be open. ### Is it free? Yes, and so is the plugin. Full docs on GitHub: https://github.com/MarkusPfundstein/mcp-obsidian --- From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt