Obsidian MCP Rs

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

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

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.