cqbase.net · English & Chinese

CQBase

Context & Query Base

MCP

Obsidian MCP

An MCP server that talks to Obsidian through the REST API community plugin, so a client can use your vault.

MarkusPfundstein/mcp-obsidian is an MIT-licensed MCP server that talks to an Obsidian vault through the REST API community plugin. An agent may therefore read or change your notes.

Vaults often hold journals and copied secrets. Start with an isolated test vault and turn off write access you do not need. Do not give a production vault token to a remote agent environment.

Mentioned by:

  • @beamnxw mentioned this project on 15 September 2026 (633 likes and 105 reposts, captured 15 November 2026).

This page is a guide, not the original text.

What problem it solves

Obsidian MCP (repository MarkusPfundstein/mcp-obsidian) lets an MCP client use your vault through Obsidian’s Local REST API community plugin. It does not walk the vault on disk. It sends requests to the plugin’s local HTTP interface. That means Obsidian has to be open, and the plugin has to be enabled.

The official README lists these tools: list_files_in_vault, list_files_in_dir, get_file_contents, search, patch_content, append_content, and delete_file. The last three change notes, and delete_file can also remove a directory.

Who it is for

It is for people who already use Obsidian and want Claude Desktop, or another MCP client, to search or organize notes. The project is MIT-licensed. It requires Python 3.11 or newer.

Vaults often hold journals and copied secrets. Start with an isolated test vault, turn off write tools you do not need, and do not give a production vault token to a remote agent environment.

How to install it

Checked on 15 November 2026 (Asia/Shanghai) against the repository README.

First install and enable the Local REST API community plugin in Obsidian, then copy the API key from the plugin settings. The default host is 127.0.0.1 and the default port is 27124. If you changed those values in the plugin, change them in the MCP config too.

The README’s client instructions are written mainly for Claude Desktop. The macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%/Claude/claude_desktop_config.json. The published package is launched with uvx:

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}

Official docs also note that Claude sometimes cannot find uv or uvx. In that case, run which uvx and put the absolute path in command. A second option is a .env file in the working directory with OBSIDIAN_API_KEY, OBSIDIAN_HOST, and OBSIDIAN_PORT. Official docs still prefer setting the values in the server config.

The repository also documents Docker. Because MCP speaks JSON-RPC over stdio, the client must use docker compose run --rm -T, not docker compose up. The example sets OBSIDIAN_HOST to host.docker.internal so the container can reach the plugin on the host.

The README does not give ready-made Cursor or Claude Code commands. Other clients that accept a standard mcpServers entry can reuse the same uvx command and environment variables, but this page does not invent a launch command that official docs do not provide.

A worked example

The prompt below is adapted from the README’s examples. It is a check, not a canned official phrase. It was not run against a live vault, so this page does not invent search results.

  1. Open a test vault that does not hold private journals or secrets. Enable Local REST API, and put the key only in the local MCP config.
  2. Keep Obsidian running, and confirm the client can see search and get_file_contents.
  3. Tell the agent to use Obsidian, then send: Search the vault for notes that mention "weekly review". Summarize the matching notes. Do not append, patch, or delete anything.
  4. Open those notes yourself and check the summary. If the agent wants to write or delete, refuse until you are on a test vault and have explicitly allowed it.

Common pitfalls

  • Connection refused because Obsidian is closed or the plugin is off. Issue #76 (still open on 15 November 2026) reports Connection refused. Confirm the plugin is listening, and that the host and port match your config.
  • Claude cannot find uvx. The README calls this out. Put the absolute path from which uvx in command.
  • Incompatibility with version 2 of the mcp Python SDK. The README pins mcp>=1.1.0,<2.0.0. An unconstrained mcp>=2.0 install can fail at import with AttributeError: 'Server' object has no attribute 'list_tools'. Issue #155 and issue #156 recorded the same class of failure (both are closed; the README pin is the current guidance).
  • A reported path-handling issue. Issue #150 (still open on 15 November 2026) reports that file paths may be built in a way that escapes the intended vault scope. This page does not repeat reproduction steps. While that issue remains open, an isolated test vault is even more important, and a production token should not go to an untrusted agent environment.
  • Write and delete tools are available by default. If you only want to search, disable those tools in the client, or do not connect a production vault yet.

FAQ

Why do I have to install the Local REST API plugin first?

This MCP server does not read the vault directory itself. It calls the plugin’s HTTP API. If the plugin is not running, tool calls have no backend. The API key also lives in the plugin settings, not in the MCP repository.

Is the port always 27124?

Official docs say the default port is 27124 and the default host is 127.0.0.1 when those values are omitted. If you changed them in the plugin, the MCP config has to change too, or the connection will fail.

Does official documentation cover Cursor or Claude Code?

The README only gives detailed steps for Claude Desktop and Docker. It does not provide a Cursor- or Claude Code-specific command. A client that uses a standard mcpServers config can theoretically reuse the same uvx entry and environment variables, but this page does not treat that as an officially verified install path.

Can I give the token to a remote agent?

That is a bad idea. The token lets its holder reach the vault through the plugin, including reads and, when those tools are enabled, edits or deletes. Official examples run the server locally and point it at 127.0.0.1. Keep a production vault token off remote or shared machines.

What should I check first when search or reads fail?

Check that Obsidian is still running, that the plugin is enabled, that the key was pasted in full, and that the host and port match. If the server never starts, look at the uvx path and whether the mcp package is still below 2.0.

Sources and license

MarkusPfundstein/mcp-obsidian is licensed under MIT. It depends on the separate Obsidian Local REST API community plugin. This page follows the README as of 15 November 2026, rewritten for CQBase — Context & Query Base. If the environment variables, the Python requirement, or the mcp pin change, follow the repository README.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.