Skip to main content
Glama

obsidian-mcp

CI

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_tool ranks notes by TF-IDF similarity so a new note doesn't duplicate an existing one under different wording

  • Schema linting — lint_schema_tool validates frontmatter against the enums declared in your own _AI_INSTRUCTIONS.md, plus an optional cron-friendly health-check script

  • Write — 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/$exists operators), or inline fields (key:: value)

  • Audit log — every write-tool call is recorded; get_audit_log_tool queries it

  • Periodic 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 formats

  • Attachments — 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 variables

  • MCP Resources & Prompts — vault notes/stats/tags as MCP resources; weekly_review/daily_note prompts

One JSON response shape across every tool — see Response Envelope.

Installation

Via uvx (no clone needed):

VAULT_PATH=/your/vault uvx obsidian-remote-mcp

Via Docker (no Python needed):

docker compose up -d   # see docker-compose.yml

From source:

git clone https://github.com/ykoellmann/obsidian-mcp.git
cd obsidian-mcp
uv sync
uv run obsidian-remote-mcp

Quick configuration

Copy .env.example to .env and set your vault path:

VAULT_PATH=/path/to/your/obsidian/vault

That'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

Configuration

Every env var: path policy, write preconditions, deletion, indexing/sync, optional tool groups, transport

Tool Reference

Every MCP tool, grouped, with the opt-in flags each needs

Response Envelope

The {success, path, revision, data, meta} shape every tool returns

Remote Setup

Running over the network: API key auth and GitHub OAuth for claude.ai

Multi-Vault Setup

Serving several isolated vaults from one deployment

Docker & Deployment

Compose, the hardened home-server profile, health checks, the schema-lint cron

Vault Conventions

Teaching the AI your vault's structure via _AI_INSTRUCTIONS.md

Architecture

Source layout and the authorization/concurrency layers underneath the tools

Development

Running tests, linting, and the local HTTP smoke test

License

MIT

Available Tools

33 tools
add_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_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

    A3.7/5.0

    Scored across 33 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes an Obsidian notes vault as MCP services, enabling AI assistants to search, read, create, update, and delete notes and folders.
      23 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to read, write, search, and manage files in an Obsidian vault via MCP over SSE, running standalone without the Obsidian desktop app.
      2
      Creative Commons Attribution Non Commercial Share Alike 4.0 International