Rust-based MCP server that connects your Obsidian vault to Claude, Cursor, and any AI client — single binary, zero runtime dependencies.

English | Русский

[!WARNING] This MCP server has full read and write access to your Obsidian vault. It can create, edit, move, and delete notes without confirmation. Use at your own risk. Always keep backups of your vault before connecting it to an AI client.

To restrict the server to read-only access, pass --no-edit — see Read-only mode.

Quick setup

Connect your vault to any AI client in seconds with the interactive wizard:

npx obsidian-mcp-rs install

The wizard scans for installed AI clients, lets you pick where to install, and writes the config automatically. Or install directly without interaction:

# Claude Desktop
npx obsidian-mcp-rs install claude ~/Documents/Obsidian/MyVault

# Claude Code – project-local (.mcp.json in current directory)
npx obsidian-mcp-rs install claude-code ~/vault

# Claude Code – global (~/.claude.json)
npx obsidian-mcp-rs install claude-code --global ~/vault

# Cursor – project-local (.cursor/mcp.json in current directory)
npx obsidian-mcp-rs install cursor ~/vault

# Cursor – global (~/.cursor/mcp.json)
npx obsidian-mcp-rs install cursor --global ~/vault

# OpenClaw
npx obsidian-mcp-rs install openclaw ~/vault

# Multiple vaults
npx obsidian-mcp-rs install claude ~/vault1 ~/vault2

Other management commands:

npx obsidian-mcp-rs list       # show installation status across all clients
npx obsidian-mcp-rs uninstall  # interactive removal wizard
npx obsidian-mcp-rs uninstall claude --dry-run  # preview changes without writing

Features

• 12 tools covering note CRUD, search, directory management, and tag operations
• Multi-vault support — pass multiple vault paths as arguments
• Read-only mode — --no-edit flag disables all write tools at the server level
• Zero runtime dependencies — single static binary, no Node.js required for execution
• Cross-platform — macOS (ARM64 + x64), Linux (x64 + ARM64 + musl), Windows (x64 + ARM64)
• Tag search via tag: prefix in queries
• YAML frontmatter tag management
• npx compatible — runs instantly via npm

Performance

Vault-wide operations (search-vault, rename-tag) walk the vault with the ignore crate and process files in parallel via rayon. Measured with the criterion suite in benches/ on a synthetic vault, Apple Silicon (10 logical cores); "serial" is the same code pinned to one thread (RAYON_NUM_THREADS=1):

| Operation | Serial (1 thread) | Parallel | Speedup | | -------------------------- | ----------------- | --------- | ------- | | Content search (2000 notes)| 52.8 ms | 26.3 ms | ~2.0× | | Tag search (2000 notes) | 45.6 ms | 24.4 ms | ~1.9× | | Tag rename (500 notes) | 84.3 ms | 60.0 ms | ~1.4× |

Single-note operations (read-note, create-note, edit-note, …) touch one file and are unaffected. Numbers vary with core count and disk; reproduce locally with cargo bench.

Installation

npm install -g obsidian-mcp-rs

Or use directly without installing (recommended):

npx obsidian-mcp-rs install   # wizard writes the config for you

Configuration

Tip: npx obsidian-mcp-rs install writes these configs automatically. The sections below are for manual setup or reference.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-rs", "/path/to/your/vault"]
    }
  }
}

Multiple vaults

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-rs",
        "/path/to/vault1",
        "/path/to/vault2"
      ]
    }
  }
}

Claude Code / CLAUDE.md

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-rs", "~/Documents/Obsidian/MyVault"]
    }
  }
}

Cursor

Add the server to Cursor's MCP settings via Settings → MCP → Add Server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-rs", "/path/to/your/vault"]
    }
  }
}

Once added, Cursor's AI will have access to all 12 vault tools. You can verify with the MCP panel in Settings.

OpenClaw (~/.openclaw/openclaw.json)

{
  "mcp": {
    "servers": {
      "obsidian": {
        "command": "npx",
        "args": ["-y", "obsidian-mcp-rs", "/path/to/your/vault"],
        "transport": "stdio"
      }
    }
  }
}

Read-only mode (--no-edit)

Pass --no-edit to start the server in read-only mode. All write tools return an error immediately — no vault files are modified.

Read-only tools (always available):

• read-note, search-vault, list-available-vaults

Blocked tools when --no-edit is set:

• create-note, edit-note, delete-note, move-note, create-directory, add-tags, remove-tags, rename-tag

Manual config with --no-edit

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-rs", "--no-edit", "/path/to/your/vault"]
    }
  }
}

Via install wizard

npx obsidian-mcp-rs install claude --no-edit ~/Documents/Obsidian/MyVault

Platform Support

| Platform | Architecture | Target triple | |----------|-------------|---------------| | macOS | ARM64 (Apple Silicon) | aarch64-apple-darwin | | macOS | x64 (Intel) | x86_64-apple-darwin | | Linux | x64 (glibc) | x86_64-unknown-linux-gnu | | Linux | ARM64 (glibc) | aarch64-unknown-linux-gnu | | Linux | x64 (musl / Alpine) | x86_64-unknown-linux-musl | | Windows | x64 | x86_64-pc-windows-msvc | | Windows | ARM64 | aarch64-pc-windows-msvc |

Tool Reference

read-note

Read the content of an existing note.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | filename | string | ✓ | Note filename (.md optional) | | folder | string | | Subfolder path within vault |

create-note

Create a new note with Markdown content.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | filename | string | ✓ | Note filename | | content | string | ✓ | Markdown content | | folder | string | | Subfolder path (created automatically) |

edit-note

Edit an existing note.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | filename | string | ✓ | Note filename | | operation | string | ✓ | append, prepend, replace, find_and_replace | | content | string | ✓ | Content to apply | | folder | string | | Subfolder path | | search | string | | Search text (required for find_and_replace) |

delete-note

Delete a note from the vault.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | filename | string | ✓ | Note filename | | folder | string | | Subfolder path |

move-note

Move or rename a note within the vault.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | filename | string | ✓ | Source filename | | folder | string | | Source folder | | newFolder | string | | Destination folder | | newFilename | string | | New filename (same if omitted) |

create-directory

Create a new directory in the vault.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | path | string | ✓ | Directory path relative to vault root | | recursive | boolean | | Create parent dirs (default: true) |

search-vault

Search notes by content, filename, or tag.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | query | string | ✓ | Search term. Use tag:name for tag search | | path | string | | Limit search to subfolder | | caseSensitive | boolean | | Default: false | | searchType | string | | content (default), filename, both |

add-tags

Add tags to notes in frontmatter and/or content.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | files | string[] | ✓ | Note filenames (include .md) | | tags | string[] | ✓ | Tags to add | | location | string | | frontmatter, content, both (default) | | normalize | boolean | | Normalize tag format (default: true) | | position | string | | start or end (default) for content tags |

remove-tags

Remove tags from notes.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | files | string[] | ✓ | Note filenames | | tags | string[] | ✓ | Tags to remove |

rename-tag

Rename a tag across all notes in the vault.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | vault | string | ✓ | Vault name | | oldTag | string | ✓ | Current tag name | | newTag | string | ✓ | New tag name |

list-available-vaults

List all vaults configured for this server. Takes no parameters.

Development

Prerequisites

• Rust (stable, 1.94+)
• Node.js 22+ (for npm wrapper)

Build from source

git clone https://github.com/MrRefactoring/obsidian-mcp-rs.git
cd obsidian-mcp-rs

# Build Rust binary
cargo build --release

# Build TypeScript wrapper
cd npm/obsidian-mcp-rs
npm install
npm run build

# Run directly
./target/release/obsidian-mcp-rs /path/to/your/vault

Testing

cargo test               # all tests (lib + integration)
cargo test --lib         # library unit tests only

Benchmarks

cargo bench                          # run the criterion suite in benches/
RAYON_NUM_THREADS=1 cargo bench      # single-threaded baseline for comparison
cargo bench --no-run                 # compile only (what CI runs)

Cross-compilation

Linux cross-compilation requires cross:

cargo install cross --git https://github.com/cross-rs/cross

cross build --release --target aarch64-unknown-linux-gnu
cross build --release --target x86_64-unknown-linux-musl

Environment variables

| Variable | Description | |----------|-------------| | RUST_LOG | Log level: error, warn (default), info, debug, trace |

Logs are written to stderr — stdout is reserved for MCP JSON-RPC.

Troubleshooting

When the server runs as a background MCP process, stderr is captured by the client and may not be visible. obsidian-mcp-rs therefore writes DEBUG logs to a file automatically whenever it starts.

Log file location

| Platform | Default path | |----------|--------------| | macOS | ~/Library/Logs/obsidian-mcp-rs/obsidian-mcp-rs.log | | Linux | ~/.local/share/obsidian-mcp-rs/obsidian-mcp-rs.log | | Windows | %LOCALAPPDATA%\obsidian-mcp-rs\obsidian-mcp-rs.log |

View logs and get a bug-report link

npx obsidian-mcp-rs logs

Prints the log file path, the last 100 lines, and a link to open a GitHub issue.

Verbose output to stderr

Useful when running the server manually in a terminal:

obsidian-mcp-rs --verbose /path/to/vault
# equivalent:
RUST_LOG=debug obsidian-mcp-rs /path/to/vault

Custom log file

# Write to a specific path:
obsidian-mcp-rs --log-file /tmp/mcp-debug.log /path/to/vault

# Disable file logging entirely:
obsidian-mcp-rs --log-file - /path/to/vault

Reporting a bug

1. Run npx obsidian-mcp-rs logs
2. Copy the output (or attach the log file)
3. Open an issue: https://github.com/MrRefactoring/obsidian-mcp-rs/issues/new

Architecture

npx obsidian-mcp-rs /vault/path
          │
          ▼
  npm/obsidian-mcp-rs/bin/bin.js   ← TypeScript platform resolver
          │   detects OS + arch
          │   resolves @obsidian-mcp-rs/<platform>
          ▼
  obsidian-mcp-rs (Rust binary)   ← MCP server, stdio transport
          │
          ├── clap → CLI args parsing
          ├── VaultManager → filesystem operations
          ├── ObsidianHandler → 12 MCP tool implementations
          └── rmcp → JSON-RPC / MCP protocol

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Implement with tests
4. Ensure cargo fmt and cargo clippy pass
5. Submit a pull request

License

MIT — see LICENSE.