Cursidian

MCP server for local Obsidian vaults, optimised for Cursor agents — safe note editing, lean tool surface, direct filesystem access. No Local REST API plugin required; Obsidian does not need to be open.

npm package: cursidian.

Features

• 13 agent-focused tools — including list_tags, search_by_tags, and get_note_neighborhood

• Safe writes — patch inferred when old_string/new_string are set; replace_section for heading edits

• Token-AND search — multi-word vault search requires all terms to appear in a note

• Optimistic concurrency — contentHash on read, optional expectedHash on write

• Signature-based caches — index and search snapshots invalidate when files change on disk (including Obsidian edits)

Related MCP server: Obsidian MCP Server

Tools (v1)

Requirements

• Node.js >= 20

• An absolute Obsidian vault path via OBSIDIAN_VAULT_PATH

Quick start (published package)

Add to ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

{
  "mcpServers": {
    "cursidian": {
      "command": "npx",
      "args": ["-y", "cursidian"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\you\\Documents\\MyVault"
      }
    }
  }
}

Unix:

"OBSIDIAN_VAULT_PATH": "/Users/you/Documents/MyVault"

Reload Cursor. The config key "cursidian" appears as MCP server user-cursidian.

See also examples/cursor-mcp.json and examples/.env.example.

Local development setup

git clone https://github.com/CoolJohn-lab/Cursidian.git
cd Cursidian
npm install
npm run build
npm test

Point Cursor at the built entrypoint:

{
  "mcpServers": {
    "cursidian": {
      "command": "node",
      "args": ["/absolute/path/to/Cursidian/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Wiki skills

Tracked skills live in skills/wiki/. Copy them into ~/.cursor/skills/ (do not symlink). Full steps: skills/wiki/INSTALL.md.

Safe write workflow

1. Read the note — note the contentHash in the response.

2. Edit using the safest mode (patch, replace_section, append, prepend, or replace).

3. Pass expectedHash from step 1 to detect concurrent edits.

Environment variables

Development

npm run dev      # run server directly (stdio)
npm test         # vitest with coverage
npm run lint     # eslint
npm run typecheck
npm run build
npm run verify   # lint + typecheck + test + build
npm run smoke    # live smoke against OBSIDIAN_VAULT_PATH

Isolated tool calls:

npm run mcp:test -- read_note --path index
npm run mcp:test -- search_content --query "wiki index" --limit 10
npm run mcp:test -- --list

Credits

Upstream filesystem MCP: @istrejo/obsidian-mcp. See LICENSE.

License

MIT — see LICENSE.