obsidian-cli-mcp

An MCP server that gives Claude and other MCP clients full control of a running Obsidian vault through the official Obsidian CLI (Obsidian 1.12+), with fast direct filesystem reads where correctness allows it.

Companion project to things-for-mac-mcp.

What makes this different?

Most Obsidian MCP servers either talk to a community REST plugin or read the vault folder directly. The first requires installing and trusting a plugin. The second silently breaks wikilinks the moment it moves or renames a file, because only Obsidian knows about every link, alias, and embed pointing at it.

This server routes every operation by capability:

The architecture mirrors its sibling project exactly:

The rule behind the split: bulk reads go to the filesystem because they need throughput, and anything that moves, renames, deletes, or depends on link resolution or app state goes through the CLI because it needs Obsidian's knowledge. The filesystem adapter structurally cannot mutate the vault, it exports no writing function at all.

Requirements

• macOS, Windows, or Linux desktop with Obsidian 1.12 or later

• The Obsidian CLI enabled: Obsidian, Settings, General, Command line interface

• Obsidian must be running. The CLI is a client to the app, not a standalone binary. This is desktop only, mobile is not supported.

• Node.js 18 or later

Installation

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

Connect to an MCP client

Claude (Desktop / Code)

Add to claude_desktop_config.json (Claude Desktop) or run claude mcp add (Claude Code):

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

Use the absolute path to node, not the bare word. GUI-launched apps do not inherit your shell's PATH, so "command": "node" fails silently in many clients. Find yours with which node.

Set OBSIDIAN_VAULT if you have more than one vault. The CLI otherwise targets whichever vault was focused last, which is a terrible property for automated writes. With a single vault the server pins it automatically at startup.

Configuration

Guardrails

Three tiers, enforced before the binary is ever spawned:

• Tier 1, free: reads, searches, and additive writes (create_note, append_note, append_daily, set_property, update_task, capture).

• Tier 2, requires confirm: true in the tool call: delete_note, move_note, rename_note, remove_property, run_obsidian_command, and through the passthrough: history:restore, publish:*, plugin:enable/disable/reload, theme:*, snippet:*, sync, sync:restore, reload, template:insert, workspace:save/delete. Any call carrying an overwrite or permanent flag is escalated to tier 2 as well.

• Tier 3, blocked unless the server runs with OBSIDIAN_MCP_ALLOW_DANGEROUS=1: eval, restart, plugin:install, plugin:uninstall, plugins:restrict, devtools, dev:cdp, dev:debug, dev:mobile, and delete_note with permanent: true.

An honest note on what these are. Tier 2 is a speed bump against accidental calls, not security: the calling model can set confirm: true itself. Tier 3 is a real boundary, because only whoever configures the server environment can unlock it. If you point an autonomous agent at a vault you care about, run with OBSIDIAN_MCP_READONLY=1, which rejects every mutating command before dispatch regardless of tier.

Link-safe moves and renames

The single most important rule in this project: files are never moved, renamed, or deleted through the filesystem. Obsidian updates every wikilink in the vault when it performs the operation. A plain mv does not.

Before, with Projects/Roadmap.md linked from three notes:

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

After move_note with to: "Archive/2026 Roadmap.md":

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

All three links updated, including the heading anchor and the alias, because Obsidian did the move. A filesystem move would have left three broken links and no error.

Why hybrid? The performance rationale

Every CLI invocation is one full IPC round trip through the running Obsidian app. That is correct but slow: reading 2,000 notes via obsidian read is 2,000 round trips, minutes of wall time. Reading them from disk is one directory walk, well under a second on any SSD.

So bulk reads (search, listings, tag and property scans, exports, digests) hit the filesystem, and the CLI is reserved for what only Obsidian can answer (links, aliases, Bases, templates, app state) and for every write. To compare on your own vault, time search_notes against the passthrough obsidian_cli with ["search", "query=..."].

Troubleshooting

"Obsidian is not running." The most common failure. The CLI needs the app open and fully loaded. Start Obsidian and retry.

"Could not find the Obsidian CLI binary." Enable the CLI in Obsidian under Settings, General, Command line interface, or point OBSIDIAN_BIN at the binary.

Timeouts on the first command. A cold Obsidian start can exceed the 20s default. Raise OBSIDIAN_MCP_TIMEOUT.

Notes read as missing or the server falls back to the CLI a lot. If your vault lives in iCloud with Optimize Mac Storage on, evicted files exist only as .name.icloud stubs. The server detects these and reads them through Obsidian, which re-downloads them, instead of reporting empty notes. Bulk scans skip evicted files and say so in their output.

Writes land in the wrong vault. You have multiple vaults and no OBSIDIAN_VAULT set. The server warns about this on stderr at startup. Pin one.

Tools do not appear in the client. Check the client's MCP logs, and check the absolute node path issue above.

Staying up to date

git pull && npm install && npm run build

The server checks for updates at startup, at most once per 24 hours, caching the result in ~/.config/obsidian-cli-mcp/update-check.json. It fails silently offline and prints a single stderr line when a newer version exists.

Tools (39 total)

Read tools (18)

Write tools (16)

All writes go through the CLI. Every one requires an explicit file or path target, none can fall through to the currently active file.

run_obsidian_command is the widest door in the server: it reaches every command palette action, including those registered by community plugins. It is exposed deliberately and gated at tier 2.

Workflow tools (4)

Escape hatch (1)

MCP Resources

Client support for resources varies, Claude Desktop does not currently surface them.

MCP Prompts

Architecture

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

Tests run against a stub binary that scans its full argv and can be told to fail, hang, or emit oversized output, so the whole suite passes with no Obsidian installed:

npm test

Support

Issues and feature requests: GitHub issues.

More from the author

• things-for-mac-mcp, the sibling MCP server for Things 3

License

MIT