Obsidian CLI MCP server

obsidian-cli-mcp

obsidian-cli-mcp is an MCP server for the official Obsidian CLI. It exposes Obsidian vault search, note, task, file, link, and native Canvas operations to an MCP client. The server does not replace Obsidian: the CLI forwards requests to the running Obsidian desktop app.

The default transport is local stdio. Remote Streamable HTTP is available as an advanced, separately secured setup; it is not required for local use.

Requirements

Command line interface**, then register obsidian on your PATH.

• macOS with Obsidian Desktop installed and running.
• The official Obsidian CLI enabled in Obsidian: **Settings → General →

build or develop this source checkout.

• Node.js 18 or newer to run the published package. Bun is only needed to

This project requires the desktop CLI. It does not support obsidian-headless. The Obsidian app must remain open while the MCP server is being used.

Check the Obsidian side first:

command -v obsidian
obsidian version
obsidian vault

Quickstart with npm

Start the published v0.4.1 package from any directory:

npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

The command speaks MCP over stdio and waits for an MCP client. It intentionally does not print protocol data to the terminal. Diagnostics go to stderr.

For a source checkout instead:

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

No vault name, vault path, token, Cloudflare account, LaunchAgent, or config file is required for the local default. The server uses the active vault that Obsidian exposes through the official CLI.

Connect an MCP client

For a client that accepts an mcpServers configuration, use the npm command:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/obsidian-cli-mcp@0.4.1",
        "obsidian-cli-mcp"
      ]
    }
  }
}

If the client does not inherit your shell PATH, replace npx with the absolute path printed by command -v npx. For a source checkout, use command: "node" and args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"].

Restart the client after changing its MCP configuration. The first useful sequence is:

example { "query": "meeting", "limit": 10 }.

1. Call vault_search with a query that should exist in your vault, for

{ "path": "" }.

1. Pass one returned path to note_read, for example

1. Preview a safe note mutation before applying it:

{
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }

This is a note_create call. It returns the planned action and exact CLI command without changing the vault. Only use dryRun: false after reviewing the plan. dryRun is a preview, not an authorization boundary.

1. For Canvas, preview a native Canvas file and one text node:

{
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }

This is a canvascreate call. Review the plan, then call it with dryRun: false if you want to create the file. Use canvasread to inspect the native .canvas JSON afterward. Canvas tools preserve unknown fields, validate node/edge references, and do not require arbitrary eval.

Configuration and safe defaults

An empty or missing configuration is usable for a vanilla Obsidian vault. The optional .obsidianmcprc.yaml is discovered from the server working directory. For clients with an unpredictable working directory, set OBSIDIANMCPCONFIG to an explicit config-file path.

Shortened. The full README is on GitHub.