obsidian-mcp

MCP server that wraps the official Obsidian CLI so an LLM agent can drive a running Obsidian instance — read/write notes, search, manage frontmatter, navigate links, run plugins, and more.

This server is a thin, comprehensive wrapper. Every tool maps 1:1 to an obsidian CLI command.

Prerequisites

1. Obsidian must be running. The CLI talks to the live app over IPC; it does not read the vault on disk directly.
2. Register the CLI binary. In Obsidian: Settings → General → Command line interface → Register CLI. Obsidian will add obsidian to your PATH.
3. Verify: obsidian version prints the CLI version.

Install

Two paths depending on whether you want to build it yourself or grab a pre-published version from npm.

Option A — Clone & build (works today)

Clone the repo and build locally, then point Claude Code at the built file:

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

Register it with Claude Code (one command):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user registers it for your whole user account. Use -s project to commit it to the repo's .mcp.json instead, or -s local for the current project only (default).

Or write it into .mcp.json manually:

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

Option B — Install from npm (zero-build)

Prerequisite: the package must already be published to npm. The maintainer publishes once via npm publish; all subsequent users get it via npx automatically. If you forked this repo and want this flow under your own scope, change name in package.json to @<your-npm-username>/obsidian-mcp, then npm publish.

Once published, no clone or build needed:

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

Or in .mcp.json / Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

Override the CLI path

If obsidian isn't on PATH, set the OBSIDIAN_CLI env var. Works with either install path:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

Tools

Vault & files

| Tool | Wraps | |---|---| | obsidian_list_files | obsidian files | | obsidian_list_folders | obsidian folders | | obsidian_read_note | obsidian read | | obsidian_get_metadata | obsidian file | | obsidian_create_note | obsidian create | | obsidian_append_note | obsidian append | | obsidian_prepend_note | obsidian prepend | | obsidian_move_note | obsidian move | | obsidian_delete_note | obsidian delete (permanent flag supported) |

Frontmatter properties

| Tool | Wraps | |---|---| | obsidian_get_properties | obsidian properties | | obsidian_set_property | obsidian property:set | | obsidian_remove_property | obsidian property:remove |

Search

| Tool | Wraps | |---|---| | obsidian_search | obsidian search | | obsidian_search_context | obsidian search:context |

Tags & links

| Tool | Wraps | |---|---| | obsidian_list_tags | obsidian tags | | obsidian_files_with_tag | obsidian tag | | obsidian_rename_tag | obsidian tags:rename | | obsidian_get_links | obsidian links | | obsidian_get_backlinks | obsidian backlinks | | obsidian_list_unresolved | obsidian unresolved | | obsidian_list_orphans | obsidian orphans |

Daily notes

| Tool | Wraps | |---|---| | obsidian_daily_read | obsidian daily:read | | obsidian_daily_append | obsidian daily:append | | obsidian_daily_path | obsidian daily:path |

Plugins

| Tool | Wraps | |---|---| | obsidian_list_plugins | obsidian plugins | | obsidian_enable_plugin | obsidian plugin:enable | | obsidian_disable_plugin | obsidian plugin:disable | | obsidian_reload_plugin | obsidian plugin:reload |

Developer / advanced

| Tool | Wraps | Notes | |---|---|---| | obsidian_eval | obsidian eval | ⚠️ Runs arbitrary JS inside Obsidian. Treat as destructive. | | obsidian_dev_screenshot | obsidian dev:screenshot | Returns base64 PNG. | | obsidian_dev_errors | obsidian dev:errors | | | obsidian_dev_console | obsidian dev:console | |

Meta

| Tool | Wraps | |---|---| | obsidian_version | obsidian version | | obsidian_help | obsidian help |

Conventions

• Targeting a note — file-targeting tools accept either:
  • file — wikilink-style note name (e.g. "My Note"), or
  • path — vault-relative file path (e.g. "Folder/My Note.md").
• Multi-vault setups — every tool accepts an optional vault parameter. When omitted, the most recently focused vault is used.
• Output format — list/search/metadata tools default to JSON for easy machine parsing.

Sensitive operations & user confirmation

The following tools are gated behind a user-confirmation step:

| Tool | Reason | |---|---| | obsidian_delete_note | Removes data (especially with permanent: true). | | obsidian_move_note | Renames + rewrites wikilinks across the vault. | | obsidian_remove_property | Removes frontmatter data. | | obsidian_rename_tag | Bulk-rewrites tags across every note. | | obsidian_enable_plugin | Grants a community plugin code execution. | | obsidian_eval | Runs arbitrary JavaScript inside Obsidian. |

How the gate works:

1. MCP elicitation (preferred). If the connected client supports the elicitation capability (Claude Code does), the server sends an elicitation/create request and the client shows the user a Proceed? prompt with the action and target spelled out. Only accept + confirm: true proceeds.
2. Explicit confirm: true parameter. Every sensitive tool's input schema includes an optional confirm: boolean. Passing confirm: true skips the elicitation prompt — use this only when the caller has already obtained user approval.
3. Refusal fallback. If the client doesn't support elicitation and confirm: true was not provided, the tool returns an isError result that names the action and instructs the caller to retry with confirm: true.

Bypass for batch / automation

OBSIDIAN_MCP_AUTO_CONFIRM=1

Set this env var (in your MCP client's env block) to skip every confirmation prompt. Use only in fully-trusted automation contexts.

Long content & argv limits

The Obsidian CLI does not (yet) support reading parameter values from stdin or from files — every value travels on the command line. That collides with platform limits:

| Platform | Practical command-line limit | |---|---| | Windows (cmd.exe) | ~8,191 chars total | | macOS / Linux | ARG_MAX (typically 128 KB – 2 MB) |

To stay safe, the server automatically chunks long writes:

| Tool | Chunking strategy | |---|---| | obsidian_create_note | First chunk via create, remaining chunks via append. | | obsidian_append_note | Sequential append calls. | | obsidian_prepend_note | prepend calls in reverse order so final order is preserved. | | obsidian_daily_append | Resolves the daily note path, then chunked append. | | obsidian_eval | Not chunked — JS can't be split. Returns an error suggesting the script-via-note workaround. |

Splits happen at line boundaries when possible; oversized single lines fall back to UTF-8-safe character boundaries. Reassembled content is byte-identical to the original.

Configure the per-call byte threshold (defaults: 6,000 on Windows, 100,000 elsewhere):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

If a chunk in the middle of a multi-chunk write fails, the server returns isError with a clear message stating which chunks made it to disk so the caller can recover.

Develop

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

How it works

runObsidian() (src/exec.ts) shell-quotes arguments, invokes the obsidian binary via child_process.exec, and parses stdout. Most read-style tools request format=json; results are parsed to structuredContent for clients that consume structured tool output, while still returning a text representation in content.

Tool registry lives in src/tools.ts — adding a new wrapped command is a single entry there.

Reference

• Obsidian CLI: https://obsidian.md/help/cli
• MCP spec: https://modelcontextprotocol.io