Obsidian MCP Server

What is Obsidian MCP Server?

This Obsidian MCP server (mcp-obsidian, by Markus Pfundstein) is an open-source Python server that lets Claude and other MCP clients list, read, search, write and delete notes in your Obsidian vault through the Local REST API community plugin.

It is a community project, not made by Obsidian. The server never touches your vault files directly. Every operation goes through the Obsidian Local REST API plugin running inside the Obsidian app, so Obsidian must be open while you use it. It is published on PyPI as mcp-obsidian, licensed MIT, and run with uvx.

How to use Obsidian MCP Server?

Prerequisites:

• Obsidian with the Local REST API community plugin installed and enabled. Copy the API key from the plugin's settings.
• uv (for uvx) and Python 3.11 or newer.

Environment variables:

• OBSIDIAN_API_KEY: the key from the Local REST API plugin (required)
• OBSIDIAN_HOST: defaults to 127.0.0.1
• OBSIDIAN_PORT: defaults to 27124

You can set these in the MCP server config (preferred) or in a .env file in the working directory.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

If Claude cannot find uvx, run which uvx and use the full path as the command.

Claude Code, Cursor and VS Code

The README documents Claude Desktop only. Because this is a standard stdio server, other clients can run the same uvx mcp-obsidian command with the same env values, for example in .cursor/mcp.json or .vscode/mcp.json. In Claude Code, add it as a stdio server that launches uvx mcp-obsidian with those three variables set.

Docker

To avoid installing uv and Python, copy .env.example to .env, run docker compose build, then point your client at the container. MCP needs stdin attached and no TTY, so use run --rm -T, not up:

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "docker",
      "args": ["compose", "-f", "<dir_to>/mcp-obsidian/docker-compose.yml", "run", "--rm", "-T", "mcp-obsidian"]
    }
  }
}

In the container, OBSIDIAN_HOST defaults to host.docker.internal so it can reach Obsidian on your machine.

Key features of Obsidian MCP Server

• Browse the vault: list the root or any folder.
• Read one note or many at once, with concatenated output for batch reads.
• Simple text search with surrounding context, plus advanced JsonLogic queries and search by tag.
• Precise edits: insert content relative to a heading, block reference or frontmatter field, or append to a file.
• Create or fully overwrite files, and delete files or folders (with an explicit confirmation flag).
• Periodic notes support: fetch the current daily, weekly, monthly, quarterly or yearly note, or recent ones.
• Recently modified files and frontmatter lookups.
• Local by design: notes stay on your machine and are accessed only through the plugin's local API.

Obsidian MCP Server tools

The current source registers 15 tools, all prefixed obsidian_. The mcp.so page and the README list the original seven.

• Navigation and reading: obsidian_list_files_in_vault, obsidian_list_files_in_dir, obsidian_get_file_contents and obsidian_batch_get_file_contents.
• Search: obsidian_simple_search (text match with context), obsidian_complex_search (JsonLogic queries, such as glob patterns on paths) and obsidian_search_by_tag.
• Writing: obsidian_append_content, obsidian_patch_content (append, prepend or replace at a heading, block or frontmatter target) and obsidian_put_content (replace the whole file).
• Deletion: obsidian_delete_file requires confirm: true.
• Metadata and periodic notes: obsidian_get_frontmatter, obsidian_get_periodic_note, obsidian_get_recent_periodic_notes and obsidian_get_recent_changes.

Use cases of Obsidian MCP Server

The README suggests first telling Claude to use Obsidian so it reliably calls the tools.

• Recall a meeting: "Get the contents of the last architecture call note and summarize them."
• Research across your vault: "Search for all files where Azure CosmosDb is mentioned and quickly explain to me the context in which it is mentioned."
• Write back: "Summarize the last meeting notes and put them into a new note 'summary meeting.md'. Add an introduction so that I can send it via email."
• Daily review: "Open today's daily note and add my three top priorities under the Tasks heading."
• Weekly cleanup: "List notes changed this week and tag the ones that are still drafts."

Obsidian MCP Server vs alternatives

Obsidian has no official MCP server, so options are community-built. mcp-obsidian works through the Local REST API plugin, which gives it heading-aware patching, periodic notes and JsonLogic search. The trade-off is that Obsidian must be running. A plain Filesystem MCP Server pointed at your vault folder works without Obsidian, but it only sees files, not Obsidian concepts like frontmatter or periodic notes. For other note apps, see Apple Notes MCP or the Notion MCP Server.

Troubleshooting Obsidian MCP Server

• Crash with AttributeError: 'Server' object has no attribute 'list_tools': the server needs the mcp Python SDK 1.x (>=1.1.0,<2.0.0). Installing with mcp>=2.0 breaks it, so use the pinned package via uvx mcp-obsidian.
• Claude cannot start the server: Claude sometimes fails to locate uv/uvx. Put the full path from which uvx in the config.
• Connection refused or timeouts: make sure Obsidian is open, the Local REST API plugin is enabled, and OBSIDIAN_HOST/OBSIDIAN_PORT match the plugin (default 127.0.0.1:27124).
• Docker container exits or hangs: run it with docker compose run --rm -T, not docker compose up, because MCP talks over stdin.
• Debugging: use the MCP Inspector (npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian run mcp-obsidian), or tail ~/Library/Logs/Claude/mcp-server-mcp-obsidian.log on macOS.