vault-mcp

MCP server for complete Obsidian vault interaction. 35 tools covering notes, search, graph, frontmatter, tags, folders, canvas, and bookmarks.

Filesystem-first: parses .md files directly from disk. No Obsidian process required. Optional REST API integration adds 3 bonus tools when Obsidian is running.

Features

Notes -- Read, create, update, patch (surgical edits), delete, move, rename. All move/rename operations automatically update wikilinks vault-wide.

Search -- Full-text search, tag search, frontmatter search, and structured power-search combining text + tags + frontmatter + folder scope with AND logic.

Graph -- Outgoing links, backlinks, orphan detection, dead-end detection, unresolved link finder.

Frontmatter -- Get, set, and remove YAML frontmatter properties.

Tags -- List all tags with counts, get note tags, rename tags vault-wide (with dry-run).

Folders -- List, create, move (with link updates), delete (empty-only safety).

Canvas -- Read and parse .canvas files into structured JSON.

Bookmarks -- Read the Obsidian bookmark tree.

Vault -- Info, stats, link resolution.

Quick Start

OBSIDIAN_VAULT_PATH="/path/to/vault" npx vault-mcp

Installation

Claude Code / Claude Desktop

Add to .mcp.json in your project root (Claude Code) or Claude Desktop config:

{
  "mcpServers": {
    "vault-mcp": {
      "command": "npx",
      "args": ["-y", "vault-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "vault-mcp": {
      "command": "npx",
      "args": ["-y", "vault-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vault-mcp": {
      "command": "npx",
      "args": ["-y", "vault-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Global Install

npm install -g vault-mcp
OBSIDIAN_VAULT_PATH="/path/to/vault" vault-mcp

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OBSIDIAN_VAULT_PATH | Yes | -- | Absolute path to your Obsidian vault | | OBSIDIAN_REST_TOKEN | No | -- | Bearer token for Obsidian REST API plugin | | OBSIDIAN_REST_PORT | No | 27124 | Port for Obsidian REST API | | OBSIDIAN_TRANSPORT | No | stdio | Transport mode: stdio or http | | OBSIDIAN_HTTP_PORT | No | 3000 | HTTP server port (when transport=http) | | OBSIDIAN_HTTP_AUTH_TOKEN | No | -- | Bearer token for HTTP transport auth |

Tools (35)

Note Operations (7)

| Tool | Description | R/W | |------|-------------|-----| | vault_read_note | Read note content and metadata | R | | vault_create_note | Create a new note | W | | vault_update_note | Replace note content | W | | vault_patch_note | Surgical edit at heading/block/frontmatter | W | | vault_delete_note | Permanently delete a note | W | | vault_move_note | Move note, update all wikilinks | W | | vault_rename_note | Rename note, update all wikilinks | W |

Search (4)

| Tool | Description | R/W | |------|-------------|-----| | vault_search | Full-text search with line-level context | R | | vault_search_by_tag | Find notes with a specific tag | R | | vault_search_by_frontmatter | Find notes by frontmatter property | R | | vault_search_structured | Power-search: text + tags + frontmatter + folder | R |

Graph (5)

| Tool | Description | R/W | |------|-------------|-----| | vault_get_links | Get outgoing links (resolved + unresolved) | R | | vault_get_backlinks | Get all notes linking to a note | R | | vault_get_orphans | Find notes with zero incoming links | R | | vault_get_dead_ends | Find notes with zero outgoing links | R | | vault_get_unresolved | Find all broken wikilinks | R |

Frontmatter (3)

| Tool | Description | R/W | |------|-------------|-----| | vault_get_properties | Get all frontmatter properties | R | | vault_set_property | Set a frontmatter property | W | | vault_remove_property | Remove a frontmatter property | W |

Tags (3)

| Tool | Description | R/W | |------|-------------|-----| | vault_list_tags | List all tags with counts | R | | vault_get_note_tags | Get tags for a specific note | R | | vault_rename_tag | Rename a tag vault-wide (supports dry-run) | W |

Folders (4)

| Tool | Description | R/W | |------|-------------|-----| | vault_list_folder | List files and subfolders | R | | vault_create_folder | Create a new folder | W | | vault_move_folder | Move/rename folder, update all wikilinks | W | | vault_delete_folder | Delete empty folder (safety constraint) | W |

Canvas (2)

| Tool | Description | R/W | |------|-------------|-----| | vault_read_canvas | Read and parse a .canvas file | R | | vault_list_canvases | List all canvas files | R |

Bookmarks (1)

| Tool | Description | R/W | |------|-------------|-----| | vault_get_bookmarks | Read the bookmark tree | R |

Vault Info (3)

| Tool | Description | R/W | |------|-------------|-----| | vault_info | Vault name, path, note/folder counts | R | | vault_stats | Detailed stats (sizes, oldest/newest, tags) | R | | vault_resolve_link | Resolve wikilink to file path | R |

REST-Only (3, requires Obsidian + REST API plugin)

| Tool | Description | R/W | |------|-------------|-----| | vault_execute_command | Execute an Obsidian command by ID | W | | vault_list_commands | List all registered Obsidian commands | R | | vault_open_in_obsidian | Open a note in the Obsidian UI | W |

Resources (7)

| URI | Description | |-----|-------------| | obsidian://vault/info | Vault info (name, path, counts) | | obsidian://vault/tags | All tags with counts | | obsidian://vault/recent | 10 most recently modified notes | | obsidian://note/{path} | Full note content + metadata | | obsidian://search/{query} | Search results | | obsidian://tag/{tag} | Notes with a specific tag | | obsidian://folder/{path} | Folder listing |

Prompts (6)

| Prompt | Description | Arguments | |--------|-------------|-----------| | daily_summary | Daily vault activity summary | date (optional) | | vault_health_check | Analyze vault health and suggest fixes | -- | | show_connections | Map connections for a note | notePath | | research_brief | Research summary on a topic from vault | topic | | inbox_processing | Process inbox notes for triage | inboxFolder (optional) | | weekly_review | Weekly review of vault changes | weekStart (optional) |

Transport

stdio (default): Standard input/output. For Claude Code, Cursor, and other local MCP clients.

OBSIDIAN_VAULT_PATH="/path/to/vault" vault-mcp

http: HTTP server at /mcp endpoint. For MCPize, remote access, or custom integrations.

OBSIDIAN_VAULT_PATH="/path/to/vault" OBSIDIAN_TRANSPORT=http OBSIDIAN_HTTP_PORT=3000 vault-mcp

REST Enhancement

Install the Obsidian Local REST API plugin to unlock 3 bonus tools. vault-mcp auto-detects the REST API at startup.

OBSIDIAN_VAULT_PATH="/path/to/vault" OBSIDIAN_REST_TOKEN="your-token" vault-mcp

Development

git clone https://github.com/afable702/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm test          # 361 tests
npm run lint      # TypeScript strict mode check
npm run build     # Build to dist/

License

Apache 2.0

MCP Servers