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

Variable	Default	Description
`OBSIDIAN_VAULT_PATH`	—	Single vault path
`OBSIDIAN_VAULTS`	—	`name=path,name2=path2` pairs
`OBSIDIAN_DEFAULT_VAULT`	first vault	Vault used when tool call omits `vault`
`OBSIDIAN_READ_ONLY`	`0`	Set to `1` to disable all writes
`OBSIDIAN_ENABLE_DELETE`	`0`	Set to `1` to allow delete operations
`OBSIDIAN_MAX_SEARCH_RESULTS`	`50`	Max results from search tools
`OBSIDIAN_MCP_PRETTY`	`0`	Pretty-print JSON responses
`OBSIDIAN_RAG_COMMAND`	`rag`	Path/command for obsidian-rag CLI
`OBSIDIAN_API_KEY`	—	Obsidian Local REST API key
`OBSIDIAN_REST_URL`	`https://127.0.0.1:27124`	Obsidian Local REST API URL
`OBSIDIAN_REST_INSECURE_TLS`	`0`	Skip TLS verification for local REST
`OBSIDIAN_ENABLE_COMMANDS`	`0`	Enable command-palette tools
`OBSIDIAN_ENABLE_UI_OPEN`	`0`	Allow `open obsidian://` system call
`OBSIDIAN_DAILY_FOLDER`	`00-Inbox`	Folder for daily notes
`OBSIDIAN_DAILY_PATTERN`	`YYYY-MM-DD.md`	Filename pattern for daily notes

Tool catalog

Discovery, search, intelligenceobsidian_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

Readingobsidian_read_note · obsidian_read_many · obsidian_get_frontmatter · obsidian_links · obsidian_get_backlinks · obsidian_canvas_read · obsidian_open_uri

Writingobsidian_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

Graphobsidian_traverse_graph · obsidian_shortest_path · obsidian_find_orphans · obsidian_find_broken_links

Tasks and assetsobsidian_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

obsidian-mcp-complete