obsidian-mcp
Allows reading, creating, and patching Excalidraw drawing files stored in an Obsidian vault when the optional Excalidraw support is enabled.
Provides comprehensive access to Obsidian vaults, including reading and writing notes, searching, link navigation, frontmatter and tag management, folder operations, backlinks, graph queries, task collection, periodic notes, attachments, templates, and multi-vault support.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-mcp search my vault for notes about MCP server setup"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
obsidian-mcp
An MCP (Model Context Protocol) server for Obsidian vaults. Connects Claude (or any MCP client) directly to your vault — read, write, search, navigate links, and manage notes, canvases, and kanban boards.
Why obsidian-mcp?
The official Obsidian MCP plugin requires the Obsidian desktop app to be running and only works on the same machine. obsidian-mcp is a standalone server — no Obsidian app needed.
The intended setup is to host obsidian-mcp on a server or NAS where your vault is continuously synced (via Syncthing, git, rclone, or Obsidian Sync). Claude then connects to that server over the network, so:
Always up to date — the server sees every change your Obsidian app writes, immediately
Access from anywhere — connect from Claude Desktop, Claude Code, or any MCP client on any machine, without the vault being present locally
Multiple clients — several Claude sessions can read the vault simultaneously; writes are serialized with per-file locking
No app dependency — the server runs headless and starts automatically (systemd, Docker, etc.)
[Obsidian app] ──sync──► [vault on server] ◄──MCP── [Claude on any machine]
(phone/laptop) (NAS / VPS) (Claude Desktop / Code)Related MCP server: obsidian-mcp-server
Features
Read & Search — read notes, search full-text (exact/regex/fuzzy, optionally combined with a frontmatter filter or scoped to filenames), render embedded transclusions, inspect note outlines, list every file in the vault regardless of type
Duplicate prevention —
find_similar_notes_toolranks notes by TF-IDF similarity so a new note doesn't duplicate an existing one under different wordingSchema linting —
lint_schema_toolvalidates frontmatter against the enums declared in your own_AI_INSTRUCTIONS.md, plus an optional cron-friendly health-check scriptWrite — create/overwrite notes (with automatic frontmatter preservation, dry-run previews, and unified diffs), patch sections or anchor-less body text, append content, update frontmatter (single or batch), manage tags, move notes with automatic wikilink rewriting
Optimistic concurrency — every read returns a revision; pass it back to a write to detect edits landed by Obsidian Sync in between
Folders — list (optionally recursive with a full tree dump), create, delete, rename folders; renaming rewrites path-based wikilinks vault-wide
Query & Graph — backlinks, broken links, orphan detection, BFS link graph, vault stats, task collection across vault
Dataview-like queries — filter notes by tags, status, frontmatter fields (exact match or
$ne/$in/$nin/$existsoperators), or inline fields (key:: value)Audit log — every write-tool call is recorded;
get_audit_log_toolqueries itPeriodic Notes — read/preview daily, weekly, monthly, quarterly, yearly journal notes from templates
Canvas / Excalidraw / Kanban / Bases (each opt-in via its own
ENABLE_*flag) — read, create, and patch these Obsidian plugin formatsAttachments — list, read (text or base64), and add binary files
Two auth variants — a static API key (Claude Code, Desktop, curl) and, optionally, GitHub OAuth (claude.ai Web/Mobile Custom Connector) — usable independently or at the same time
Multi-vault (opt-in) — serve several fully isolated vaults from one deployment, each identity mapped to only the vault(s) it may access
Templates — render Obsidian templates with built-in (
{{date}},{{title}}, …) and custom variablesMCP Resources & Prompts — vault notes/stats/tags as MCP resources;
weekly_review/daily_noteprompts
One JSON response shape across every tool — see Response Envelope.
Installation
Via uvx (no clone needed):
VAULT_PATH=/your/vault uvx obsidian-remote-mcpVia Docker (no Python needed):
docker compose up -d # see docker-compose.ymlFrom source:
git clone https://github.com/ykoellmann/obsidian-mcp.git
cd obsidian-mcp
uv sync
uv run obsidian-remote-mcpQuick configuration
Copy .env.example to .env and set your vault path:
VAULT_PATH=/path/to/your/obsidian/vaultThat's enough for local stdio use. For network transports, path
restrictions, optional plugin-format tools, and every other variable, see
Configuration.
Usage with Claude Code / Desktop
Add to your MCP config (~/.claude/mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"obsidian": {
"command": "uv",
"args": ["--directory", "/path/to/obsidian-mcp", "run", "obsidian-remote-mcp"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}Documentation
Topic | |
Every env var: path policy, write preconditions, deletion, indexing/sync, optional tool groups, transport | |
Every MCP tool, grouped, with the opt-in flags each needs | |
The | |
Running over the network: API key auth and GitHub OAuth for claude.ai | |
Serving several isolated vaults from one deployment | |
Compose, the hardened home-server profile, health checks, the schema-lint cron | |
Teaching the AI your vault's structure via | |
Source layout and the authorization/concurrency layers underneath the tools | |
Running tests, linting, and the local HTTP smoke test |
License
MIT
Available Tools
33 toolsadd_attachment_toolC
Write a binary attachment (image, PDF, etc.) to the vault from base64-encoded content. data: {size_bytes, mime_type}.
Inputs: path (required), content_base64 (required), vault. Returns: object
append_to_note_toolA
Append content to a note without reading and rewriting the whole file. section: optional heading to append under. create=True creates the note if missing.
Inputs: path (required), content (required), vault, create, +2 more. Returns: object
create_attachment_token_toolA
Create a short-lived, single-file upload/download token for the GET/PUT /attachments/{path} HTTP route, instead of handing out the server's master API_KEY. method: 'PUT' (upload) or 'GET' (download). expires_in: seconds until the token expires (default 300, max 3600).
If the server has
PUBLIC_BASE_URL configured, url is the ready-to-use request URL — use
it as-is, it already has everything this token needs (including
?vault= when relevant) baked in. Otherwise build it yourself as:
curl -X PUT --data-binary @file.png
"http://host:port/attachments/{path}?exp={expires_at}&sig={sig}&vault={vault}"
(omit &vault=... only if the returned vault equals the server's
single/default vault — see list_vaults_tool). The token only authorizes
this exact path + method + vault and stops working after expires_at. In
multi-vault mode, requires an api_key identity — GitHub-OAuth identities
have no static secret of their own to sign with; use a plain
Authorization: Bearer request against /attachments/* instead (that path
works for any identity type, but needs ?vault= added by hand if
targeting a non-default vault, since nothing was pre-signed for it).
data: {method, vault, expires_at, sig, url?}.
Inputs: path (required), vault, method, expires_in. Returns: object
create_folder_toolB
Create a folder (and any missing parents) in the vault. Returns {path, status}.
Inputs: path (required), vault. Returns: object
create_from_template_toolB
Render a template and write it as a new note.
Built-in variables: {{date}}, {{time}}, {{title}}, {{week}}, {{month}}, {{year}}, {{weekday}}.
Supports format specs: {{date:YYYY-MM}} → '2026-07'.
Custom variables passed in 'variables' dict override built-ins.
Unknown {{vars}} are preserved as-is.
path is the written note; data: {template, variables}.
Inputs: output_path (required), template_path (required), vault, variables, +2 more. Returns: object
find_similar_notes_toolA
Find conceptually related notes even when the wording differs — for duplicate prevention before creating a new note ("does this topic already exist under different vocabulary?"). Ranks by TF-IDF cosine similarity over the vault's own vocabulary (a lightweight heuristic, not a transformer embedding model — it catches shared distinctive words across differently-phrased notes, not pure synonym rewrites). exclude_path: skip a note (e.g. the one you're editing) from results. min_score: filters out noise-level matches (0-1, higher = stricter). data.items: [{path, score}], most similar first.
Inputs: text (required), limit, vault, min_score, +1 more. Returns: object
get_audit_log_toolA
Query the append-only log of write-tool activity (who/what changed, not just the .trash/ state after the fact). Most recent first. path/tool/since are optional filters (since: ISO timestamp, inclusive). Entries: {timestamp, tool, path, summary}. Covers the core note/folder write tools; canvas/kanban/excalidraw/bases writes aren't logged yet.
Inputs: path, tool, limit, since, +1 more. Returns: result
get_backlinks_toolB
Return all notes that link to the given note (alias-aware). data.items is a list of note paths.
Inputs: path (required), vault. Returns: object
get_broken_links_toolB
Find all wikilinks in the vault that point to non-existent notes. data.items: [{source, link}].
Inputs: vault. Returns: object
get_link_graph_toolC
Return a traversable link graph starting from a note.
direction: 'outgoing' | 'incoming' | 'both'.
path is the resolved root note; data: {nodes: [{path, title, tags}],
edges: [{from, to, type}]}.
Inputs: root (required), depth, vault, direction. Returns: object
get_orphans_toolA
Find notes that no other note links to. Excludes Journal and Templates by default. data.items is a list of paths.
Inputs: vault, exclude_folders. Returns: object
get_periodic_note_toolA
Read or preview a periodic note. period: 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'. date: 'today' | 'yesterday' | 'YYYY-MM-DD'. data: {period, date, exists, content, frontmatter, tasks}.
Inputs: date, vault, period. Returns: object
get_tasks_toolA
Return tasks from across the vault.
status: 'open' | 'done' | 'all'. Optionally filter by folder or tag.
due_before/due_after: 'YYYY-MM-DD', inclusive; matches the Tasks-plugin
📅 due date (tasks without one never match either filter).
Parses Tasks-plugin emoji markers: 📅 due, ✅ done date, 🔁 recurrence,
⏫/🔼/🔽 priority (high/medium/low) — stripped from text into their own fields.
data.items: [{text, done, source, line, due, recurrence, priority, done_date}].
Inputs: tag, vault, folder, status, +2 more. Returns: object
get_vault_conventions_toolA
Return the vault's AI instructions / conventions from _AI_INSTRUCTIONS.md. data.conventions is the raw Markdown.
Inputs: vault. Returns: object
get_vault_stats_toolB
Return vault statistics: note count, link count, orphans, broken links,
most-linked notes. Vault-wide, so the envelope carries no path.
Inputs: vault. Returns: object
lint_schema_toolA
Validate every note's frontmatter against the enum fields declared in
the vault's _AI_INSTRUCTIONS.md (under a "Frontmatter Schema" heading,
e.g. status: inbox | active | done | archived). Returns
{schema, violations: [{path, field, found, expected_enum}]} — only the
deviations, not a full vault dump. A field that's simply missing on a
note isn't a violation, only a present value outside the declared enum
is. Returns an empty schema/violations pair if no enum schema can be
parsed from _AI_INSTRUCTIONS.md.
Inputs: vault. Returns: object
list_all_tags_toolA
Return every tag in the vault.
mode:
'flat' (default) — data.items: [{tag, count}], with note counts. sort_by: 'count' (descending, default) | 'name' (alphabetical).
'tree' — data.tree: the same tags as a nested mapping that follows the slash hierarchy (e.g. konzept → python, ki → llm). sort_by is ignored.
Inputs: mode, vault, sort_by. Returns: object
list_attachments_toolB
List all non-Markdown files in the vault: images, PDFs, audio, etc. data.items: [{path, size_bytes, mime_type, mtime}].
Inputs: vault, folder. Returns: object
list_files_toolA
List every file in the vault (or a subfolder), any type — not just notes/attachments/bases/canvases (e.g. .lock files, stray non-Markdown files). extension filters by suffix without the dot (e.g. "lock", "canvas"); omit for everything. Hidden files/folders are skipped. data.items is a list of vault-relative paths.
Inputs: vault, folder, extension. Returns: object
list_folder_toolA
List the contents of a vault folder (non-hidden items only). path='': root of the vault. recursive=False (default): immediate contents only — data: {folders, files}. recursive=True: full tree dump in one call — data: {tree: {folders: {name: tree}, files: [...]}}. max_depth limits how many levels deep to descend (None = unlimited).
Inputs: path, vault, max_depth, recursive. Returns: object
list_notes_toolA
List all Markdown notes in the vault (or a subfolder). Set include_meta=True to get title, tags, status, created per note. data.items is a list of paths, or of {path, title, tags, status, created, mtime} when include_meta=True.
Inputs: vault, folder, include_meta. Returns: object
list_templates_toolC
List all template files in the Templates/ folder. data.items is a list of template paths.
Inputs: vault. Returns: object
list_vaults_toolA
List the vault(s) the current identity (API key or GitHub login) may access. Returns [{name, description, is_default}]. Call this at the start of a session whenever more than one vault comes back — pass vault= on any other tool to operate on a non-default one for that single call; omit it to use whichever entry has is_default=true. In single-vault mode (no VAULTS_CONFIG) this always returns exactly one entry with is_default=true — there's nothing to choose between. data.items: [{name, description, is_default}].
Inputs: no named parameters. Returns: object
manage_tags_toolA
Add or remove tags on a note. Updates frontmatter tags array and strips inline #tag occurrences from the body. Returns {added, removed}.
Inputs: path (required), add, vault, remove, +1 more. Returns: object
patch_frontmatter_toolA
Update specific YAML frontmatter keys without touching the note body.
Pass path for one note, or paths to apply the same updates to
several notes in one call — exactly one of the two.
merge_arrays=True merges list values (e.g. tags); False replaces them. dry_run=True previews data {preview, diff, updated_keys} without writing — check it, then call again with dry_run=False.
With path: data carries {updated_keys, diff} and the envelope a
revision. With paths: one note failing doesn't abort the rest — this
returns the batch envelope, with data.results holding one item per note
({success, path, revision} or {success: false, path, error}) and
data.summary the {total, succeeded, failed} tally. Always check
data.summary.failed. expected_revision pins a single note's bytes and so
can't be combined with paths.
Inputs: path, paths, vault, dry_run, +3 more. Returns: object
patch_note_text_toolA
Find and replace text anywhere in one note's body — no heading/block-ref
anchor required, unlike patch_note_tool. Cheaper than write_note_tool for
a scattered single-note edit (e.g. bumping one enum value inside a long note).
mode: 'exact' (default, literal substring) | 'regex'.
count: max replacements (default 1, first match only); 0 = replace all.
dry_run=True previews {replacements, preview, diff} without writing.
Raises ValueError if find doesn't match anything.
Inputs: find (required), path (required), replace (required), mode, +4 more. Returns: object
patch_note_toolA
Edit a section or block reference inside a note. mode: 'replace' (default) | 'insert_before' | 'insert_after' | 'append'. target_type: 'heading' (default) | 'block_ref' (use section='^block-id'). dry_run=True previews data {preview, diff} without writing — check it, then call again with dry_run=False.
Inputs: path (required), section (required), new_content (required), mode, +4 more. Returns: object
query_notes_toolA
Dataview-like query: filter notes by tags, status, frontmatter, or inline fields. tags: all must match (AND). sort_by: 'path'|'title'|'created'|'mtime'. inline_field_filter: match Dataview inline fields (key:: value syntax). data.items: [{path, title, tags, status, created, mtime, frontmatter, inline_fields}].
Inputs: tags, limit, vault, folder, +5 more. Returns: object
read_attachment_toolC
Read an attachment file. data.content is a UTF-8 string for text files, or base64-encoded bytes for binary ones (images, PDFs) — data.mime_type and data.encoding say which.
Inputs: path (required), vault. Returns: object
read_note_toolA
Read one note at the level of detail you actually need.
mode:
'full' (default) — data: {content, frontmatter, tags, aliases, wikilinks, block_refs, callouts, tasks, inline_fields}.
'outline' — structure only, no body text: data: {headings, block_refs, frontmatter_keys, tags, aliases, inline_fields, word_count, line_count}. Use this on a large note when you only need its shape.
'rendered' — data: {rendered}, the note with all ![[embed]] transclusions resolved inline.
depth applies to mode='rendered' only: 0=raw, 1=one level of embeds (default), 2=nested embeds.
The envelope's revision is the token to pass back as expected_revision
when writing (modes 'full' and 'outline'; a rendered read spans several
notes, so it pins nothing).
Inputs: path (required), mode, depth, vault. Returns: object
resolve_alias_toolA
Resolve a note alias or stem to its real vault path.
path and data.resolved are null (and path omitted) if not found.
Inputs: name (required), vault. Returns: object
search_notes_toolA
Full-text search with snippets and relevance ranking. mode: 'exact' (default) | 'regex' | 'fuzzy'. data.items: [{path, score, snippets, tags}]. frontmatter_filter: combine with the text search in one call — same shape as query_notes_tool's (plain value = exact match, or {"$ne": v} / {"$nin": [...]} / {"$exists": bool}). field: None/'body' (default, search note content) | 'filename' (match only the file name). threshold: fuzzy-match similarity cutoff 0-1 (only used when mode='fuzzy'; lower = looser matches, higher = less noise).
Inputs: query (required), tag, mode, field, +4 more. Returns: object
write_note_toolA
Write (create or overwrite) a note. Respects READ_ONLY and WRITE_PATHS.
If content has no frontmatter of its own and a note already exists at
path, its existing frontmatter is preserved rather than dropped —
check the returned frontmatter_preserved flag. The result also carries
a diff (unified diff against the current file).
dry_run=True previews {preview, diff, frontmatter_preserved} without
writing anything — check it, then call again with dry_run=False.
Inputs: path (required), content (required), vault, dry_run, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool targets a distinct operation: reading, writing, searching, patching (section/text/frontmatter), managing attachments, templates, folders, tags, tasks, periodic notes, link graph, and vault stats. Overlapping tools like write_note vs patch_note vs append are clearly differentiated by descriptions.
All 33 tools follow a consistent verb_noun_tool pattern in snake_case (e.g., list_notes_tool, read_note_tool, create_folder_tool). Verb choices (list/get/read/query/patch/manage) align with their actions, making naming predictable and unambiguous.
33 tools is high but appropriate for the broad scope of full Obsidian vault management—covering notes, attachments, templates, tasks, periodic notes, frontmatter, and vault health. Some tools like create_attachment_token are niche, but they fill real gaps. Slightly heavy, yet each earns its place.
The surface is largely complete: full note lifecycle (create/read/update via write/patch/append), search, query, linking, tags, attachments, templates, folders, and vault stats. Missing delete_note and move/rename operations are notable gaps, and exotic formats (canvas/kanban) aren't supported, but core workflows are covered.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes an Obsidian notes vault as MCP services, enabling AI assistants to search, read, create, update, and delete notes and folders.23 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables local MCP clients to list, read, write, and search notes in an Obsidian vault via an HTTP server running inside Obsidian.1-
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to read, write, search, and manage files in an Obsidian vault via MCP over SSE, running standalone without the Obsidian desktop app.2Creative Commons Attribution Non Commercial Share Alike 4.0 International
- AlicenseAqualityBmaintenanceEnables MCP clients to safely read, search, create, edit, delete, and move notes in an Obsidian vault, with automatic link repair and reversible deletes.10MIT