Obsidian Cli

An MCP server that wraps the official Obsidian CLI (obsidian, bundled with the Obsidian desktop app) instead of the Local REST API plugin. Each server instance is pinned to a single vault, so you run one entry per vault.

Why the CLI instead of the REST API?

The REST-API MCP (mcp-obsidian) needs the Local REST API community plugin, an API key, and a dedicated port per vault. This server drives the Obsidian app through its built-in CLI, which needs no plugin and no API key, and exposes a much richer surface: tasks, frontmatter properties, backlinks, search-with-context, vault metadata, and more.

Requirement: the Obsidian desktop app must be running with the target vault open. The CLI talks to the live app, not the files on disk.

Install

The server is a uv project. No global install is needed — MCP clients launch it on demand with uv run.

git clone <this repo> && cd obsidian-cli-mcp
uv sync          # install dependencies
uv run pytest    # run the test suite (no live Obsidian needed)

Configure (per vault)

Add one entry per vault to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json). The vault is selected with the OBSIDIAN_VAULT environment variable — run obsidian vaults to see the exact names.

{
  "mcpServers": {
    "obsidian-cli-void": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/obsidian-cli-mcp", "obsidian-cli-mcp"],
      "env": { "OBSIDIAN_VAULT": "void" }
    },
    "obsidian-cli-notebook": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/obsidian-cli-mcp", "obsidian-cli-mcp"],
      "env": { "OBSIDIAN_VAULT": "notebook" }
    }
  }
}

Environment variables

Variable	Required	Default	Purpose
OBSIDIAN_VAULT	yes	—	Vault name this instance targets (injected as vault= on every call).
OBSIDIAN_CLI_PATH	no	obsidian	Path to the CLI binary if it isn't on PATH.
OBSIDIAN_VERIFY_READS	no	true	Run the vault guard before reads too (not just writes).
OBSIDIAN_ALLOW_PERMANENT_DELETE	no	false	Allow delete_note(permanent=True) to bypass trash.
OBSIDIAN_TIMEOUT	no	30	Per-command subprocess timeout (seconds).
OBSIDIAN_GUARD_TTL	no	5	Seconds to cache a successful vault-guard check.
OBSIDIAN_LOG_LEVEL	no	INFO	Log level (logs go to stderr).

Tools

Read / navigate: read_note, search_vault, list_files, list_folders, note_info, list_backlinks, list_tags, list_tasks, list_properties, read_property, vault_info, list_vaults

Write / organise: create_note, add_to_note, set_property, remove_property, move_note, rename_note, delete_note, update_task

Escape hatch: run_obsidian — run any other CLI command (e.g. bookmarks, wordcount, history). Disruptive commands (restart, reload, eval, devtools, plugins:restrict, and all dev:*) are blocked.

Notes are addressed by file (resolve by name, like a wikilink) or path (exact folder/note.md). Most read tools fall back to the active note when both are omitted; write tools require an explicit target.

Safety: the vault guard

The Obsidian CLI silently falls back to the active vault when vault=<name> names a vault that isn't currently open. To prevent acting on the wrong vault, this server verifies — via vault info=name — that the configured vault is the one actually responding before every write (and before reads, by default). If it isn't, the tool fails with a clear message instead of touching another vault.

This also means the CLI reports failures on stdout with exit code 0; the server detects them by inspecting the output, so genuine errors surface as MCP tool errors rather than being mistaken for success.

License

MIT © digster