obsidian-cli-mcp

obsidian-cli-mcp

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