obsidian-mcp-rs
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Rust MCP server for Obsidian vaults — read, write, search notes via Model Context Protocol. Works with Claude, Cursor, and any MCP client.
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.
Ask your AI to connect Obsidian
Connect my Obsidian vault to this AI client. Follow https://github.com/MrRefactoring/obsidian-mcp-rs/blob/master/INSTALL.md. Ask me for the vault path and use my preferred language.
Official sources: GitHub Releases, npm, and crates.io.
Setup
Choose npm or Cargo to install the server. Both paths run the same installer, which copies the server to a fixed location and configures your client. Node is not needed to run the installed server.
Cargo
Install from source with Rust and Cargo, then configure your client:
cargo install --locked obsidian-mcp-rs
obsidian-mcp-rs install claude-code ~/Documents/Obsidian/MyVault
Ensure Cargo’s bin directory is on your PATH. Replace claude-code and the vault path for your setup. You can also run obsidian-mcp-rs install for the interactive wizard.
If you have cargo-binstall, use cargo binstall obsidian-mcp-rs to install a prebuilt release instead of compiling. Then run the same obsidian-mcp-rs install command above.
npm
The npm installer requires Node.js 22 or newer.
Not inside an agentic client — e.g. Claude Desktop, which can't run shell commands — or just prefer to do it yourself? The interactive wizard scans for installed AI clients, lets you pick where to install, and writes the config automatically:
npx obsidian-mcp-rs install
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 # installation status across all clients, and which server version is installed
npx obsidian-mcp-rs uninstall # interactive removal wizard
npx obsidian-mcp-rs uninstall claude --dry-run # preview changes without writing
What install actually writes
It copies the server binary to a fixed per-user location and writes that absolute path into your client config:
| Platform | Installed server |
|---|---|
| macOS | ~/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs |
| Linux | ~/.local/share/obsidian-mcp-rs/bin/obsidian-mcp-rs |
| Windows | %LOCALAPPDATA%\obsidian-mcp-rs\bin\obsidian-mcp-rs.exe |
Your config therefore runs one process — the server itself, as a direct child of your AI client. It does not run npx, which would start three (npm → a Node launcher → the server) and leave the extra two behind whenever a client terminates only the first. It also means the server can tell when your client goes away, and exit with it instead of lingering with write access to your vault.
Run the installer with either npx obsidian-mcp-rs install or obsidian-mcp-rs install after installing with Cargo. Neither command puts npx in the client config.
Updating
The server keeps itself up to date, from 0.8.0 onwards. Once install has placed it, it checks for a new release at most once a day, in the background, and replaces itself when it finds one.
Auto-update ships in 0.8.0, so it cannot bring you 0.8.0 — an older copy does not know how. Run
npx obsidian-mcp-rs@latest installonce and it takes over from there.npx obsidian-mcp-rs listsays so if your copy predates it. Nothing is asked of you, and nothing is interrupted — the new version is what your client starts next time it launches.
Four things it deliberately will not do:
- It waits 48 hours after a release ships. If a release turns out to be broken, that window is when it gets withdrawn — so the bad one never reaches you.
- It only ever replaces the copy
installplaced. A binary fromcargo install, from a distribution package, or the onenpxcaches belongs to whatever put it there. Those never update themselves. - It asks the network at most once a day per machine, no matter how many times your client restarts the server — and a failed check is silent, so an offline or firewalled machine is never slowed down or broken by it.
- It verifies what it downloads against the checksum published with the release, and runs the new binary once before installing it. Anything that does not answer with the version it claims is thrown away.
Turning it off goes through an install, because that is where the answer is recorded:
npx obsidian-mcp-rs@latest install claude ~/vault --no-auto-update
Name the client and the vault. The bare install --no-auto-update starts the interactive wizard, and the wizard only records your answer once you have picked a client — so backing out of it changes nothing. The wizard asks instead of assuming and offers your current choice as the default. The answer is remembered; the same command with --auto-update takes it back. An install that says nothing about auto-update changes nothing about it, so configuring a second client will not switch it back on.
To take a release now rather than wait for the check, run the installed copy — update acts on the binary that is running it, and the copy in npm's cache is not the one in your configs. npx obsidian-mcp-rs list prints the path:
# macOS; see the table above for Linux and Windows
"$HOME/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs" update # take the latest release
"$HOME/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs" update --check # just say what is available
"$HOME/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs" update --force # take it even inside the 48-hour hold
What the check sends. One GET to api.github.com per day, carrying what any HTTP request carries — your IP address — and a User-Agent of obsidian-mcp-rs/<version>. An actual update then downloads the binary from github.com, which redirects to githubusercontent.com. Nothing about your vaults, your notes, your client or your machine is sent, and nothing identifies you across days beyond what GitHub can infer from an address. It honours HTTP_PROXY / HTTPS_PROXY / NO_PROXY. If that is one request too many, --no-auto-update stops it entirely.
To go back to an older release, install it with auto-update off — npx [email protected] install claude ~/vault --no-auto-update. Without that flag the daily check follows releases/latest in both directions and puts the newer one back within a day, which is deliberate: withdrawing a bad release means dropping it out of releases/latest, and everyone who already took it has to be able to come back down. The path in your configs never changes, so nothing needs re-pointing either way. (One exception, and it catches everyone who installed early: a config written before 0.7.0 does not hold that path yet, so none of this reaches it — see below.)
npx obsidian-mcp-rs list prints where the server is, which version it is, and whether auto-update is on.
On Windows, quit your AI clients before running install. Windows refuses to overwrite a running executable; if a client still has the server open the installer will say so and ask you to close it. (update is not affected — it renames rather than overwrites.)
uninstall removes the binary too, once no client config still points at it.
Upgrading from a config written before 0.7.0
Everything above describes a config install wrote for you. If yours predates 0.7.0 it holds npx -y obsidian-mcp-rs, or a resolved path into npm's _npx cache, and re-running install will not replace it.
The installer refuses to overwrite an entry that differs from the one it would write — that entry may be something you tuned by hand, and silently discarding it is worse than doing nothing. So it reports the entry and moves on:
! Claude Code – global (~/.claude.json) already installed in ~/.claude.json, but with different settings than you asked for
nothing was changed — re-run with --force to replace that entry
That line sits between the clients that were written and the "restart your client" note at the end, which is an easy place to miss it. If your client still starts npx after an update, this is why — and none of the process-lifecycle fixes above are in effect for it.
To migrate, add --force:
npx obsidian-mcp-rs@latest install --force
Every backend copies the previous file to <config>.bak before writing, so this is reversible.
list names the ones that need it:
! Claude Desktop outdated …/claude_desktop_config.json — runs `obsidian-vault-mcp`, not the installed server; re-run `install --force`
! Claude Code – global (~/.claude.json) outdated ~/.claude.json — runs `npx`, not the installed server; re-run `install --force`
✓ Codex CLI – global installed ~/.codex/config.toml
outdated means the entry is there and does not launch this server. Earlier versions reported every one of these as installed, because the check asked only whether an obsidian key existed — which is also why a config naming a binary that had since been deleted went unnoticed.
Known issues that are not ours
- Duplicate server processes on Claude Desktop. Claude Desktop can spawn more than one copy of the same MCP server per launch (claude-code#36616). Nothing this server does causes it, and nothing it does can prevent it. It is safe: concurrent servers on one vault are serialised so they cannot lose each other's edits, and any that outlive their client exit on their own.
- Orphaned MCP processes generally. Several clients fail to terminate stdio MCP servers on unclean exit (#22612, #1935, #40667). This server watches the process that started it and exits when it goes, on all three platforms: a
getppidpoll on macOS and Linux, a wait on the parent's process handle on Windows. - Two devices, one synced vault. Writes are serialised per machine. Two computers editing the same cloud-synced vault at once is a sync conflict, and it belongs to iCloud / Obsidian Sync rather than to this server.
Features
- 25 MCP tools for notes, search, links, properties, tasks, Canvas, and Obsidian Markdown guidance
- Ranked search — BM25 relevance with field boosts (a term in the title outranks the same term buried in a paragraph), returned best-first and capped so a common word can't flood the model's context
- Link-aware moves update inbound Markdown links and Canvas cards. Batch previews list affected files and blockers before you confirm the move.
- Link graph —
vault_linksanswers backlinks, outgoing, broken links and orphans - Section-scoped edits — point
edit_noteat one heading or one^block-idand only those bytes are rewritten; the rest of the note is passed through untouched - Frontmatter access —
note_propertiesreads and writes any YAML key, not justtags, and touches only the key you named - Multi-vault support — pass multiple vault paths as arguments
- Recoverable deletes —
delete_notemoves the note to the vault's.trash/(as Obsidian does) rather than erasing it; a trashed note disappears from search and the link graph, but the user can still get it back - Daily notes —
periodic_notesreads/creates daily…yearly notes using the vault's own Obsidian settings (name format, folder, template), so it writes to the note you actually keep - Vault orientation —
vault_infoanswers what tags exist, what changed recently, and how big the vault is - Write controls with read-only mode, folder allowlists, and revision checks for note edits
- Markdown tasks stay in their source notes. Find, add, finish, or reschedule tasks and preview changes across files.
- JSON Canvas lets agents read or edit nodes and edges while preserving untouched fields.
- Zero runtime dependencies — the server is a single static binary, and it is what your client runs:
installplaces it and points the config straight at it, so no Node process sits in between. Node.js 22+ is needed only to run the installer; grab a binary from Releases orcargo installto skip it entirely. - Cross-platform — macOS (ARM64 + x64), Linux (x64 + ARM64 + musl), Windows (x64 + ARM64)
- Tag search via
tag:prefix in queries - YAML frontmatter tag management
- Streamable HTTP (optional) —
cargo install obsidian-mcp-rs --features http, then--httpserves several clients from one long-lived server. Validates theOriginheader, as the MCP spec requires of local servers. stdio remains the default. npxcompatible — try it or install it in one command, with nothing to download first
Search
search_notes ranks hits with BM25, the same scoring family a full-text engine uses — but computed straight from the parallel vault walk, so there is no index to build, no watcher to keep in sync, and nothing to go stale when you edit a note in Obsidian.
Terms are weighted by where they occur: filename ×5, tags ×4, headings ×3, frontmatter ×2, body ×1. Rare terms count for more than common ones, so a query like the kafka ranks the note about Kafka above the note that merely says "the" a lot.
Results are paged (limit, default 20; offset) and each file quotes at most maxMatchesPerFile lines (default 3). Every response carries total and truncated, so the model can see that more matches exist without you paying for them in context.
Ranking answers "which notes are about this". Two questions it can't answer have their own arguments:
regex: true— match a shape rather than words: a phone number, aTODO(name), a URL. Hits are then ranked by how many lines matched, since relevance means nothing for a pattern.frontmatter: {"status": "active"}— keep only notes carrying those fields. A list field matches when it contains the value, so{"tags": "work"}finds a note withtags: [work, urgent]. Combine it with a query, or use it alone with an empty query as a pure metadata lookup ("every active note in this vault").
Both are computed inside the walk that already reads every note, so neither costs an extra pass.
Performance
Vault-wide operations (search_notes, rename_vault_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 |
|---|---|---|---|
| Ranked search (2000 notes) | 52.8 ms | 26.2 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.
Configuration
Tip:
npx obsidian-mcp-rs installwrites these configs automatically, including the absolute path below — you do not have to work it out yourself. The sections below are for manual setup or reference.
commandis the pathinstallreports, e.g.~/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rson macOS (spelled out in full — configs do not expand~). Do not putnpxhere: it starts three processes where one is needed, leaves two of them behind when a client shuts the server down, and hides your client's exit from the server so it cannot clean up after itself.
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"obsidian": {
"command": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": ["/path/to/your/vault"]
}
}
}
Multiple vaults
{
"mcpServers": {
"obsidian": {
"command": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": [
"/path/to/vault1",
"/path/to/vault2"
]
}
}
}
Claude Code (.mcp.json / ~/.claude.json)
Claude Code's config carries an explicit "type": "stdio" (Claude Desktop, above, omits it):
{
"mcpServers": {
"obsidian": {
"type": "stdio",
"command": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": ["~/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": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": ["/path/to/your/vault"]
}
}
}
Once added, Cursor's AI will have access to all 25 MCP tools in the default configuration. You can verify with the MCP panel in Settings.
OpenClaw (~/.openclaw/openclaw.json)
{
"mcp": {
"servers": {
"obsidian": {
"command": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": ["/path/to/your/vault"],
"transport": "stdio"
}
}
}
}
Read-only mode (--no-edit)
Pass --no-edit to start the server in read-only mode. The thirteen write-only tools are removed from tools/list and cannot be called.
Removed under --no-edit (the write-only tools):create_note, edit_note, delete_note, move_note, create_folder, add_note_tags, remove_note_tags, rename_vault_tag, create_task, update_task, apply_task_batch, create_canvas, edit_canvas
Still listed, because they read as well as write — these are gated per action, so the reads work and the writes are refused:
note_properties—getworks;setandremoveare refusedperiodic_notes—getandlistwork;createis refusedbatch_move_notes— preview works; applying a preview is refused
Pure reads, always available:read_note, search_notes, vault_links, vault_info, list_vaults, get_writing_guide, list_tasks, preview_task_batch, read_canvas
Limit writes to selected folders
Pass --write-folder VAULT=FOLDER when starting the server or running install. Use a vault name from list_vaults and a vault-relative folder path. Repeat the flag for multiple folders. Use VAULT=. to allow writes in all folders of one vault. If a vault name is ambiguous, use its canonical path.
obsidian-mcp-rs install claude --write-folder "MyVault=Inbox" ~/Obsidian/MyVault
With at least one rule, all configured vaults remain readable and only listed folders allow writes. A move or tag rename fails before it changes files if it needs to update a protected note. A normal delete from an allowed folder can move the note to the vault trash. Without rules, the server uses the default full write access. --no-edit disables writes regardless of these rules.
Manual config with --no-edit
{
"mcpServers": {
"obsidian": {
"command": "/Users/you/Library/Application Support/obsidian-mcp-rs/bin/obsidian-mcp-rs",
"args": ["--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 |
Import notes
Use import-markdown for a local folder of Markdown notes and attachments. The command reads an existing MCP connection to select the vault and enforce its write rules. Omit --apply to preview the files, link changes, and blockers. Check the plan with the person who owns the vault before applying it with the same arguments and returned plan_id.
obsidian-mcp-rs import-markdown --client claude-code --vault MyVault --source ./export --folder Inbox
obsidian-mcp-rs import-markdown --client claude-code --vault MyVault --source ./export --folder Inbox --apply "$PLAN_ID"
Use --global for a global connection. Use one --exclude PATH per source-relative path to skip. Use --allow-missing-attachments only when the user accepts the unresolved attachments listed in the preview. The offline import preserves source files and rejects occupied destinations.
For other formats supported by the official Obsidian Importer, ask the user before opening it. obsidian-mcp-rs open-importer --vault MyVault opens the Importer for the named vault when Obsidian CLI and the official Importer plugin are available. The user chooses the source and confirms the import in Obsidian. Import guide
Tool Reference
Migration: Tool names changed to the snake_case names below. Update clients that call the old names; aliases are not provided.
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 | |
view |
string | content (default) or outline — headings, block refs and frontmatter keys |
|
offset |
number | First line to return, 1-based (default 1) | |
limit |
number | Most lines to return (default 400) |
Reads are capped so that one long note cannot consume the model's whole context. Past the limit the note is cut off with a marker saying which lines you got and what offset to pass for the rest; a note that fits comes back untouched. offset speaks the same line numbers view: "outline" prints, so one can be pasted straight into the other.
The second text block contains the revision of the complete file, even for an outline or partial response.
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) |
|
targetType, target |
string | Select a heading or block. Pass both fields together. | |
expectedRevision |
string | Revision returned by the read. If the file changed, read it again before applying the edit. |
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. Omit to keep the note where it is — that is how you rename in place. Pass "" to move it to the vault root. |
|
newFilename |
string | New filename (same if omitted) |
Pass at least one of newFolder or newFilename. The move rejects an occupied destination. It updates inbound Markdown links and Canvas file cards, and reports any link updates that could not finish after the move.
create_folder
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_notes
Search notes by content, filename, or tag. Results are BM25-ranked, best-first, and paged.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
query |
string | ✓ | Search term. tag:name searches a tag. May be empty when filtering by frontmatter alone |
path |
string | Limit search to subfolder | |
caseSensitive |
boolean | Default: false |
|
searchType |
string | content (default), filename, both |
|
regex |
boolean | Read query as a regular expression (default false) |
|
frontmatter |
object | Only notes carrying these fields, e.g. {"status": "active"}. A list field matches when it contains the value |
|
limit |
number | Files to return (default 20) | |
offset |
number | Skip this many files (default 0) | |
maxMatchesPerFile |
number | Lines quoted per file (default 3) |
Each hit carries a path — pass it straight back as any note tool's filename.
vault_links
The vault's link graph, in one parallel pass.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
query |
string | ✓ | backlinks, outgoing, broken, or orphans |
filename |
string | The note to ask about — required by backlinks and outgoing |
|
folder |
string | Subfolder containing the note | |
limit |
number | Default 50 — broken and orphans run to thousands on a neglected vault |
|
offset |
number | Skip this many (default 0) |
Links inside code fences are ignored: a [[link]] in a code sample is documentation, not a reference.
note_properties
Read or write any YAML frontmatter key — not just tags. Writes are line surgery on the one key named, so the rest of the block (comments, key order, quoting) survives byte for byte.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
filename |
string | ✓ | Note path |
action |
string | ✓ | get, set, or remove |
key |
string | Which field. Omit with get to return the whole block |
|
value |
any | What to write — string, number, boolean, list or object (set only) |
|
folder |
string | Subfolder containing the note |
Under --no-edit this is gated per action: get works, set/remove are refused.
vault_info
What's actually in this vault — the questions you ask before you know what to search for.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
query |
string | ✓ | tags (every tag + how many notes carry it, commonest first), recent (newest first), or stats |
limit |
number | Cap the list (default 20) |
periodic_notes
Today's daily note, and its weekly/monthly/quarterly/yearly siblings — read from Obsidian's own settings (the Periodic Notes plugin's data.json, then core's daily-notes.json, then Obsidian's defaults), so it lands where Obsidian would rather than creating a stray note.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
period |
string | ✓ | daily, weekly, monthly, quarterly, yearly |
action |
string | ✓ | get, create (idempotent), or list |
date |
string | YYYY-MM-DD — defaults to today |
|
content |
string | Text for a note create brings into existence; without it, the configured template is used |
|
limit |
number | How many notes list walks back (default 10) |
add_note_tags
Add tags to notes in frontmatter and/or content.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
files |
string[] | ✓ | Vault-relative note paths. All must exist — if any doesn't, nothing is changed |
tags |
string[] | ✓ | Tags to add |
location |
string | frontmatter, content, or both (default). Note that both puts the tag in the note twice |
|
normalize |
boolean | Normalize tag format (default: true) |
|
position |
string | start or end (default) — where an inline tag goes |
remove_note_tags
Remove tags from notes.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
files |
string[] | ✓ | Note filenames |
tags |
string[] | ✓ | Tags to remove |
rename_vault_tag
Rename a tag across all notes in the vault.
The tool is available when the server has write access.
| Parameter | Type | Required | Description |
|---|---|---|---|
vault |
string | ✓ | Vault name |
oldTag |
string | ✓ | Current tag name |
newTag |
string | ✓ | New tag name |
dryRun |
boolean | Set to true to list the notes that would change without writing to them. The default is false. |
list_vaults
List all vaults configured for this server. Takes no parameters.
get_writing_guide
Read Obsidian Markdown rules, examples, and note recipes. This tool works offline and is available in read-only mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
topics |
string[] | Up to four different topic names. Omit to list the topics. |
For example, request {"topics":["links","callouts","meeting"]}. Use the official obsidian-markdown skill when it is installed. Use the sources topic to see the pinned upstream revision and license.
Task tools
| Tool | Use |
|---|---|
list_tasks |
Find Markdown checkboxes in a vault, recursive folder, note, or today's daily note. Filter by status, dates, priority, tags, or blockers. Use next_offset to read more. |
create_task |
Add a task to a note or daily note. Select a section with destination.heading. |
update_task |
Pass the task's path, line, and revision from list_tasks. Change its text, status, due or scheduled date, or priority. |
preview_task_batch |
Preview up to 50 moves or date changes. Review warnings and affected files with the user. |
apply_task_batch |
After confirmation, submit the same operations and plan_id. Inspect per-file results if the batch stops before completion. |
For example, {"vault":"MyVault","status":"todo","date":{"field":"due","match":"overdue"}} lists overdue tasks. Use scope: {"kind":"today"} to find tasks written in today's daily note. The tools keep tasks in their source notes. Supported Obsidian Tasks fields, recurrence, and ready-to-use prompts are listed in the workflow guide. Task workflows
Canvas tools
| Tool | Use |
|---|---|
read_canvas |
Read a board's nodes, edges, and revision by vault-relative path. |
create_canvas |
Create a board at an unused path. Pass JSON Canvas nodes and edges, or create an empty board. |
edit_canvas |
Pass expectedRevision and add, update, or remove nodes and edges. Existing nodes keep their positions unless you change them. |
Omit both x and y to place a new node automatically. Use node IDs in edge endpoints and edit patches. JSON Canvas format
batch_move_notes
Submit moves, each with sourceVault, sourcePath, destinationVault, and destinationPath. Use exact vault-relative note paths. The response lists changes and blockers and returns preview_id. Use offset and limit to page through the details.
Show the preview to the user before applying it. Use allowAttachmentCopy if the user agrees to copy referenced files while keeping the originals. Use allowEmbedConversion and allowCanvasConversion only if the user agrees to convert cross-vault embeds and Canvas file cards to clickable links. If you change an option, get a new preview. To apply, send the same moves and options with previewId. If a file changed since the preview, review and confirm a new plan.
Development
Prerequisites
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
# If you started the server with --log-file, point `logs` at the same path,
# or it will show you the default log while yours fills up elsewhere.
npx obsidian-mcp-rs logs --log-file /tmp/mcp-debug.log
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
- Run
npx obsidian-mcp-rs logs - Copy the output (or attach the log file)
- 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 → 25 MCP tool implementations
└── rmcp → JSON-RPC / MCP protocol
Contributing
See CONTRIBUTING.md for development setup, checks, and pull requests.
Community rules are in CODE_OF_CONDUCT.md.
Report vulnerabilities through the private contact in SECURITY.md.
License
MIT — see LICENSE.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found