diegosouzapw--omniroute/docs/frameworks/OBSIDIAN_CONTEXT.md

title, version, lastUpdated

title	version	lastUpdated
Obsidian Context Source	3.8.40	2026-06-28

Obsidian Context Source

Source of truth: src/lib/obsidian/api.ts (REST + sync client), src/lib/db/obsidian.ts (token / base-URL / WebDAV persistence), src/lib/obsidianSync.ts (WebDAV vault sync), open-sse/mcp-server/tools/obsidianTools.ts (22 MCP tools), src/app/api/settings/obsidian/route.ts + src/app/api/settings/obsidian/webdav/route.ts (settings APIs). Tool registration and scope wiring lives in open-sse/mcp-server/server.ts.

What it is

OmniRoute connects to an Obsidian vault as a context source — a local Markdown knowledge base that agents read and write through the built-in MCP server. The integration talks to the Obsidian Local REST API community plugin running inside the desktop app, so agents can search notes, read/write/patch files, list the vault, work with daily/weekly periodic notes, manage tags, run Obsidian commands, and (optionally) coordinate a bidirectional desktop↔mobile vault sync.

The client (src/lib/obsidian/api.ts) wraps the Local REST API with:

• Retry with backoff for transient 5xx, 30-second timeout via AbortController.
• Typed error classification — ObsidianAuthError (401/403), ObsidianNotFoundError (404), ObsidianServerError (5xx), ObsidianTimeoutError.
• A friendly "cannot reach Obsidian" hint that calls out the common port mistake (HTTP on 27123, not the MCP endpoint on 27124) and the Tailscale form.
• Vault-relative path encoding so note paths with spaces/slashes are safe.

Setup

There is no environment variable for the Obsidian token or base URL — both are stored in the SQLite key_value table (namespace obsidian) via src/lib/db/obsidian.ts. The token is encrypted at rest (AES-256-GCM, with plaintext backward-compat fallback). Configure from the Context Sources tab of the Endpoint dashboard (ObsidianSourceCard), or via the settings REST API.

Important

The Obsidian Local REST API plugin must be installed and running. Its REST interface listens on HTTP 127.0.0.1:27123 (the default base URL). Port 27124 is a separate MCP/HTTPS endpoint and is explicitly rejected by the settings route. If connecting from another device, use http://<tailscale-ip>:27123.

Configuration keys (SQLite key_value, namespace obsidian)

Key	Purpose	Encrypted
api_key	Local REST API bearer token	yes
base_url	REST base URL (default http://127.0.0.1:27123)	no
vault_path	Absolute path to the vault directory (for sync)	no
webdav_username	Generated WebDAV username (vault sync)	no
webdav_password	Generated WebDAV password (vault sync)	yes
webdav_enabled	Whether WebDAV vault sync is enabled	no

Configure via REST

# Save + validate the Local REST API token (POST validates via a status check)
curl -X POST http://localhost:20128/api/settings/obsidian \
  -H "Content-Type: application/json" \
  -d '{"token":"<obsidian-rest-api-key>","baseUrl":"http://127.0.0.1:27123"}'

# Check connection status (returns connected, hasToken, baseUrl, vaultPath)
curl http://localhost:20128/api/settings/obsidian

# Disconnect (clears the stored token)
curl -X DELETE http://localhost:20128/api/settings/obsidian

All methods require dashboard authentication. POST rejects any URL on port 27124 and validates the token by calling the Local REST API status endpoint before persisting.

WebDAV vault sync

src/app/api/settings/obsidian/webdav/route.ts manages an optional WebDAV-backed vault sync (driven by src/lib/obsidianSync.ts). Enabling it points OmniRoute at a local vault directory and mints a random WebDAV username/password pair:

# Enable WebDAV sync for a vault directory (mints username/password)
curl -X POST http://localhost:20128/api/settings/obsidian/webdav \
  -H "Content-Type: application/json" \
  -d '{"vaultPath":"/home/me/MyVault"}'

# Get WebDAV sync status (credentials returned only while enabled)
curl http://localhost:20128/api/settings/obsidian/webdav

# Disable WebDAV sync (clears credentials + managed .stignore)
curl -X DELETE http://localhost:20128/api/settings/obsidian/webdav

Per-API-key context source (optional)

Obsidian config can be scoped per API key via the api_key_context_sources table (src/lib/db/apiKeyContextSources.ts). When an MCP call carries an authenticated API key id, getObsidianConfigForApiKey() prefers that key's own token/base-URL/vault-path (source: "api_key") and otherwise falls back to the global config (source: "global").

MCP tools (22)

Defined in open-sse/mcp-server/tools/obsidianTools.ts. The token/base-URL are resolved per call (per-API-key first, then global). Tools that hit the OmniRoute sync server (the four obsidian_sync_* tools) additionally require the sync auth token configured in OmniRoute settings.

Read tools (read:obsidian)

Tool	Description
obsidian_check_status	Check whether the Local REST API is reachable and authenticated.
obsidian_search_simple	Full-text search of note content; returns snippets with file paths.
obsidian_search_structured	Search using a JSON Logic expression (and/or/regex/path filters).
obsidian_read_note	Read a note by vault-relative path; optionally a specific heading/block/frontmatter.
obsidian_list_vault	List files and directories in the vault (tree of entries).
obsidian_get_document_map	Get the note's heading structure as a map of headings → line numbers.
obsidian_get_note_metadata	Get frontmatter, tags, links, char/word count without the full content.
obsidian_get_active_file	Get the path + content of the currently active file in Obsidian.
obsidian_get_periodic_note	Get the daily/weekly/monthly periodic note for a date (today if omitted).
obsidian_get_tags	List all vault tags with their frequencies.
obsidian_list_commands	List available Obsidian command IDs (use with obsidian_execute_command).
obsidian_sync_status	OmniRoute sync server status: running, vault name, port, uptime, last sync.
obsidian_sync_conflicts	List unresolved sync conflicts (path, conflict path, detected-at).

Write tools (write:obsidian)

Tool	Description
obsidian_write_note	Create or overwrite a note with given Markdown content.
obsidian_append_note	Append content to a note; optionally to a specific heading/block.
obsidian_patch_note	Surgically append/prepend/replace at a heading, block, or frontmatter field.
obsidian_delete_note	Permanently delete a note from the vault.
obsidian_move_note	Move or rename a note within the vault.
obsidian_execute_command	Execute an Obsidian command by its command ID.
obsidian_open_file	Open a file in Obsidian (creates it if it does not exist).
obsidian_sync_trigger	Trigger an immediate bidirectional desktop↔mobile vault sync.
obsidian_sync_resolve_conflict	Resolve a sync conflict: keep local (mobile), remote (desktop), or keep-both.

Note

obsidian_patch_note targets accept targetType of heading | block | frontmatter and operation of append | prepend | replace, with an optional createTargetIfMissing. The four obsidian_sync_* tools talk to the local sync server (http://127.0.0.1:27781 by default) and require the sync token.

Scopes

Read tools require read:obsidian; write tools require write:obsidian. Enforcement is identical to Notion — handled by withScopeEnforcement() in open-sse/mcp-server/server.ts, gated on OMNIROUTE_MCP_ENFORCE_SCOPES=true, with allowed scopes sourced from OMNIROUTE_MCP_SCOPES or the API key's scope context. See MCP-SERVER.md.

Endpoints

Method	Path	Purpose
GET	/api/settings/obsidian	Return { connected, hasToken, baseUrl, vaultPath }.
POST	/api/settings/obsidian	Save + validate token (rejects port 27124).
DELETE	/api/settings/obsidian	Disconnect (clear stored token).
GET	/api/settings/obsidian/webdav	WebDAV sync status + credentials (while enabled).
POST	/api/settings/obsidian/webdav	Enable WebDAV sync for a vault directory.
DELETE	/api/settings/obsidian/webdav	Disable WebDAV sync.

These are dashboard settings routes. The vault itself is reached through the Obsidian Local REST API (the configured base_url) and through the MCP tools above — there is no public /v1 Obsidian proxy endpoint.

Use cases

• Vault-grounded answers — obsidian_search_simple / obsidian_search_structured then obsidian_read_note so an agent answers from your real notes.
• Note authoring / journaling — obsidian_write_note, obsidian_append_note, or the surgical obsidian_patch_note to log agent output, summaries, or daily notes (obsidian_get_periodic_note) into the vault.
• Vault navigation — obsidian_list_vault, obsidian_get_document_map, and obsidian_get_tags to explore structure before reading/writing.
• Obsidian automation — obsidian_list_commands + obsidian_execute_command to drive plugins/commands from an agent; obsidian_open_file to surface a note in the UI.
• Mobile sync — enable WebDAV sync, then obsidian_sync_trigger / obsidian_sync_status / obsidian_sync_conflicts / obsidian_sync_resolve_conflict to coordinate desktop↔mobile and resolve conflicts.

Related

• MCP Server — transports, scope enforcement, full tool inventory.
• Notion Context Source — the other built-in context source.
• Memory System — persistent conversational memory (complementary context layer, injected automatically rather than tool-fetched).