obsidian-mcp-complete

Local-first MCP server for Obsidian vaults. Works without Obsidian running, no plugins required.

66 tools across: read/write/search notes, BM25 smart search, graph traversal, JSON Canvas, tasks, periodic notes, frontmatter, batch ops, and an optional bridge to the Obsidian Local REST API.

Install

npx (zero install, always latest)

npx obsidian-mcp-complete "/path/to/vault"

npm global

npm install -g obsidian-mcp-complete
obsidian-mcp "/path/to/vault"

Homebrew

brew tap jagoff/obsidian-mcp
brew install obsidian-mcp
obsidian-mcp "/path/to/vault"

Smithery (MCP store)

Search for obsidian-mcp-complete at smithery.ai and configure from the UI.

Configure in Claude Code / Claude Desktop

Add to your ~/.claude/claude_desktop_config.json (Desktop) or ~/.mcp.json (Claude Code):

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

Multi-vault with named vaults:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y", "obsidian-mcp-complete",
        "notes=/Users/you/Documents/Notes",
        "work=/Users/you/Documents/work-vault"
      ],
      "env": {
        "OBSIDIAN_DEFAULT_VAULT": "notes",
        "OBSIDIAN_MAX_SEARCH_RESULTS": "80"
      }
    }
  }
}

Environment variables

Tool catalog

Discovery, search, intelligence obsidian_status · obsidian_list_vaults · obsidian_list_files · obsidian_search · obsidian_smart_search · obsidian_search_paths · obsidian_recent_notes · obsidian_vault_stats · obsidian_rag_query · obsidian_query_notes · obsidian_list_tags · obsidian_graph_stats · obsidian_vault_graph · obsidian_vault_themes · obsidian_vault_suggest · obsidian_diff_notes

Reading obsidian_read_note · obsidian_read_many · obsidian_get_frontmatter · obsidian_links · obsidian_get_backlinks · obsidian_canvas_read · obsidian_open_uri

Writing obsidian_create_note · obsidian_upsert_note · obsidian_append_to_note · obsidian_patch_note · obsidian_replace_in_note · obsidian_regex_replace · obsidian_update_frontmatter · obsidian_manage_tags · obsidian_move_note · obsidian_update_links · obsidian_batch_rename · obsidian_delete_note · obsidian_delete_folder · obsidian_prune_empty_dirs · obsidian_batch_create_notes · obsidian_batch · obsidian_update_task · obsidian_daily_note · obsidian_periodic_note · obsidian_apply_template · obsidian_import_attachment · obsidian_write_canvas · obsidian_canvas_create · obsidian_canvas_patch · obsidian_canvas_relayout

Graph obsidian_traverse_graph · obsidian_shortest_path · obsidian_find_orphans · obsidian_find_broken_links

Tasks and assets obsidian_list_tasks · obsidian_list_attachments

Obsidian Local REST API (requires plugin + OBSIDIAN_API_KEY) obsidian_rest_status · obsidian_rest_request · obsidian_get_active · obsidian_post_active · obsidian_put_active · obsidian_patch_active · obsidian_delete_active* · obsidian_list_commands* · obsidian_execute_command* · obsidian_search_dataview · obsidian_search_jsonlogic · obsidian_open_in_ui†

* requires OBSIDIAN_ENABLE_COMMANDS=1 · † requires OBSIDIAN_ENABLE_UI_OPEN=1

Security

• Paths are validated and scoped to configured vault roots — traversal and absolute paths are rejected

• .obsidian/ and .git/ directories are never exposed

• Writes are atomic (write to temp + rename)

• Delete is opt-in (OBSIDIAN_ENABLE_DELETE=1) and requires explicit confirmation field

• Read-only mode disables all mutations (OBSIDIAN_READ_ONLY=1)

Development

git clone https://github.com/jagoff/obsidian-mcp
cd obsidian-mcp
npm install
npm run build
npm test

Smoke test:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/stdio.js "/path/to/vault"

Release

Tag a version to trigger the release workflow (CI → npm publish → GitHub Release):

git tag v0.2.0
git push origin v0.2.0

Requires NPM_TOKEN secret set in the GitHub repo settings.

Inspired by

• @bitbonsai/mcpvault — direct vault access without plugins

• cyanheads/obsidian-mcp-server — surgical frontmatter editing

• yanxue06/obsidian-mcp and aaronsb/obsidian-mcp-plugin — graph, backlinks, daily notes, batch ops