obsidian-mcp

A local MCP server that lets an AI agent (Claude Cowork, Claude Code, any MCP client) move and rename notes and folders in an Obsidian vault while keeping links intact — something a plain mv cannot do.

It drives the running Obsidian app through its official CLI, so link updates are performed by Obsidian itself, exactly as with drag-and-drop in the file explorer.

Why

Agents usually manipulate a vault as plain files. Moving a note with mv breaks every link pointing to it, because only Obsidian maintains the link index. Some agents (e.g. Claude Cowork) even run their shell in a Linux VM where the Obsidian app is unreachable. A local MCP server, launched on the host by the desktop client, bridges that gap.

Related MCP server: Obsidian MCP Server

Tools

Paths are relative to the vault root. The tool list is deliberately closed: no generic access to obsidian eval.

Requirements

• macOS, Obsidian ≥ 1.12 running, with the CLI enabled: Settings → General → Command line interface.

• Obsidian setting Automatically update internal links enabled.

• Python ≥ 3.12.

Installation

Install the package into a dedicated environment, so the server clients launch is independent from the source checkout:

conda create -n obsidian-mcp python=3.12
conda run -n obsidian-mcp pip install .      # re-run after each code change

Executable: <env>/bin/obsidian-mcp.

Environment variables:

• OBSIDIAN_VAULT: name of the target vault (defaults to the active vault);

• OBSIDIAN_BIN: path to the Obsidian executable (defaults to /Applications/Obsidian.app/Contents/MacOS/Obsidian).

Client configuration

Claude Desktop (and therefore Cowork) — ~/Library/Application Support/Claude/claude_desktop_config.json, edited while Claude Desktop is closed:

"mcpServers": {
  "obsidian-vault": {
    "command": "/path/to/envs/obsidian-mcp/bin/obsidian-mcp",
    "env": { "OBSIDIAN_VAULT": "MyVault" }
  }
}

Claude Code:

claude mcp add -s user obsidian-vault -e OBSIDIAN_VAULT=MyVault -- /path/to/envs/obsidian-mcp/bin/obsidian-mcp

The client starts the server (stdio subprocess) when it launches and stops it when it quits.

Making agents actually use it

Having the tools available is not enough: out of habit, an agent may still reach for mv. The server sends a short instruction to clients, but an explicit rule in the agent's own context is more reliable. Suggested wording:

- Moving or renaming a note or folder in the vault: only with the `vault_*` tools
  of the `obsidian-vault` MCP server, which go through Obsidian and update links.
  Never `mv`, `git mv`, or copy-then-delete. If these tools are unreachable
  (Obsidian closed, desktop app not running), ask the user to do the move in Obsidian.

Where to put it:

• A CLAUDE.md at the vault root: read by Claude Code, and by Cowork when the vault is the working folder. One place covers both.

• Cowork without the vault as working folder: in Cowork's global instructions, or in a small skill (e.g. "obsidian-vault-ops") whose description triggers on moving, renaming or reorganising notes.

• Claude Code, hard enforcement (optional): a PreToolUse hook on Bash that rejects mv/git mv commands touching the vault path turns the rule into a guard.

Notes

• obsidian move refuses folders, hence the eval route for vault_move_folder.

• When a folder is moved, Obsidian may rewrite path-qualified links to their shortest form (depending on your New link format setting); links remain valid.

License

MIT