Skip to main content
Glama
obsidian-vault-mcp

obsidian-vault-mcp

obsidian-vault-mcp

A filesystem-based MCP server for Obsidian vaults. Works when Obsidian is closed.

The problem

Every existing Obsidian MCP connector requires Obsidian to be running and the Local REST API plugin active. When Obsidian goes to the background or is closed, the connector drops — silently, mid-session.

Related MCP server: pablo-obsidian-mcp

The solution

This server reads and writes your vault directly from disk via Node's fs module. No Obsidian process required. No plugin dependencies. No background disconnects.

Tools

  • list_vault_files — list vault files, optionally filtered by directory

  • get_vault_file — read a file's content

  • append_to_vault_file — append content (creates file and dirs if needed)

  • create_vault_file — create or overwrite a file

  • patch_vault_file — insert/replace content relative to a heading

  • search_vault_simple — plain-text substring search across all notes

patch_vault_file supports three operations relative to any heading:

  • append — add content after the heading's section

  • prepend — add content immediately after the heading line

  • replace — replace the entire heading section with new content

Install

Download obsidian-vault-mcp.mcpb from the latest release and double-click it. Claude Desktop handles the rest.

Option B — Build from source

Requires Node.js 18+.

git clone https://github.com/WhiteWolf-Cyber/obsidian-vault-mcp cd obsidian-vault-mcp npm install npm run build

Claude Desktop config

Add to mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json:

macOS / Linux

{ "Obsidian Vault": { "command": "node", "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"], "env": { "OBSIDIAN_VAULT_PATH": "/Users/yourname/ObsidianVault" } } }

Windows

{ "Obsidian Vault": { "command": "node", "args": ["C:\Users\yourname\dev\obsidian-vault-mcp\dist\index.js"], "env": { "OBSIDIAN_VAULT_PATH": "C:\Users\yourname\Documents\ObsidianVault" } } }

Restart Claude Desktop after saving.

Vault path

The vault path resolves in this order:

  1. OBSIDIAN_VAULT_PATH environment variable

  2. ~/ObsidianVault (fallback)

Security

Paths are validated at runtime — requests that resolve outside VAULT_PATH are rejected. The server never traverses above the vault root.

Mobile setup (remote access via Cloudflare Tunnel)

The same 21 vault tools are also served over HTTP/SSE so Claude on iOS/iPad can reach your vault as a custom connector. This is purely additive — the stdio transport above continues to work unchanged for Claude Desktop.

  1. Install cloudflared: brew install cloudflare/cloudflare/cloudflared

  2. Authenticate with Cloudflare: cloudflared tunnel login

  3. Create the tunnel: cloudflared tunnel create obsidian-vault-mcp

  4. Copy the tunnel UUID printed by the previous command into cloudflare-tunnel.yml (replace <tunnel-id> in the credentials-file path).

  5. Set VAULT_MCP_SECRET in your environment (or skip this and let the server generate one — it will print it to stderr on first run, copy it from there).

  6. Start the HTTP server: npm run start:http

  7. Run the tunnel: cloudflared tunnel run obsidian-vault-mcp (or install cloudflared as a launchd service for persistent background operation on macOS — see Cloudflare's launchd service docs for the plist template.)

  8. In the Claude iOS/iPad app, add a custom connector:

    • URL: https://vault.envoyagent.app/sse

    • Authorization: Bearer <your VAULT_MCP_SECRET>

Restarting the connector

If the connector seems stuck, the 10-second I/O timeout guard (see withTimeout in src/tools.ts) will surface a clear error instead of hanging silently. To restart the HTTP transport itself:

pkill -f http-server.js
npm run start:http

No Claude Desktop restart is needed — this only affects the HTTP/SSE transport, not the stdio connection Claude Desktop uses.

Env vars

VAULT_MCP_SECRET=<generate with: openssl rand -hex 32 — do not commit>
PORT=3456
OBSIDIAN_VAULT_PATH=/Users/darrellmahrle/dev/vault

Built by

EnvoyAgent — AI-powered outbound voice appointment setting.

Available Tools

21 tools
append_to_vault_fileA

Append content to a vault file, creating the file and any missing parent directories if needed.

Inputs: path (required), content (required).

create_vault_directoryB

Create a directory (and any missing parents) inside the vault.

Inputs: path (required).

create_vault_fileA

Create (or overwrite) a vault file with the given content, creating any missing parent directories.

Inputs: path (required), content (required).

delete_vault_directoryA

Delete a directory inside the vault. Non-recursive fails if the directory is not empty.

Inputs: path (required), recursive.

delete_vault_fileC

Delete a single vault file.

Inputs: path (required).

get_files_by_tagA

List vault files that contain a given #tag, with per-file occurrence counts.

Inputs: tag (required), limit.

get_note_outlineC

Get the heading outline of a vault file.

Inputs: path (required).

get_note_propertyB

Get a YAML frontmatter property's value from a vault file.

Inputs: key (required), path (required).

get_recent_filesB

List vault markdown files sorted by most recently modified first.

Inputs: limit.

get_vault_fileB

Get the contents of a vault file by its vault-relative path.

Inputs: path (required).

get_vault_file_partialA

Get the content of a single heading's section from a vault file (heading line through the next same-or-higher-level heading, exclusive).

Inputs: path (required), target (required), targetType (required).

list_tagsA

List all #tags used across the vault with their occurrence counts.

Inputs: no named parameters.

list_vault_filesC

List markdown (.md) files in the vault, optionally under a subdirectory.

Inputs: limit, directory.

patch_vault_fileB

Patch a vault file relative to a markdown heading: append/prepend content within the heading's section, or replace the section's content entirely.

Inputs: path (required), target (required), content (required), operation (required), +1 more.

rename_headingC

Rename a heading's text in a vault file, preserving its level.

Inputs: path (required), newHeading (required), oldHeading (required).

rename_vault_fileA

Rename/move a vault file and update [[wikilinks]] referencing its old filename across the vault.

Inputs: path (required), newPath (required).

search_and_replaceC

Find and replace text across the vault (or a single file). Supports literal or regex patterns.

Inputs: pattern (required), replacement (required), path, isRegex.

search_vault_simpleB

Case-insensitive substring search across all vault markdown files.

Inputs: query (required), limit.

set_note_propertyA

Set (or add) a YAML frontmatter property on a vault file, creating a frontmatter block if none exists.

Inputs: key (required), path (required), value (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, from file/directory CRUD to specialized operations like heading manipulation, tag listing, and link tracking. Overlaps are minimal and well-differentiated.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, e.g., create_vault_file, get_backlinks, search_and_replace. This pattern is predictable and aids agent understanding.

    Tool Count5/5

    With 21 tools, the set is well-scoped for managing an Obsidian vault. It covers essential operations without being overwhelming.

    Completeness5/5

    The tool surface covers file/directory CRUD, search, tag management, link tracking, frontmatter properties, and heading operations. No obvious gaps for typical vault management tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides read and write access to an Obsidian vault by interacting directly with markdown files on disk. Supports searching, listing, reading, creating, editing, and appending notes without requiring any Obsidian plugins.
      ISC
    • A
      license
      A
      quality
      C
      maintenance
      A filesystem-based MCP server for Obsidian vaults that enables LLMs to browse, search, read, write, and edit Markdown notes directly on disk without requiring Obsidian to be running.
      6
      1
      CeCILL-B Free Software Agreement
    • A
      license
      A
      quality
      C
      maintenance
      A headless MCP server for interacting with Obsidian vaults, enabling AI assistants to search, read, edit, and manage notes and their structure without a GUI.
      25
      1
      MIT