Optimike Obsidian MCP
French version: README.fr.md · Documentation hub · Operations · Security
Optimike Obsidian MCP gives MCP clients a governed operational surface over an Obsidian vault: live Desktop operations, resilient headless modes, Tasks and Operon, Bases and Canvas, semantic search, runtime observability, and bounded access to configured external documents. Version 3.9 adds bounded note-link observation, governed native note move, durable absent-only creation and a single-row Base property patch. Each mutation uses a distinct plan → apply → status lifecycle and fails closed when its sealed proof cannot be reconciled. See the qualification protocol and bounded roadmap. Version 3.10 improves retrieval and semantic diagnostics, serves legacy and MCP 2026-07-28 clients side by side, and can publish explicitly configured Agent Skills as read-only resources. Host support for native Skills must be verified separately. The Operon Bridge also remains responsive with the Obsidian window hidden. See the dual-stack contract and Skills publication contract. Version 3.11 adds opt-in event-assisted cache refresh and governed ChatGPT image import with a portable, explicitly configured image policy. It also corrects Smart Connections v3 model selection, HTTP response framing and Operon scheduling, and clarifies task creation and recovery contracts.
Version 3.12 adds the operational profile, read-only frontmatter access and faster governed completion with a qualified optional FDM integration. See the measured gains and conditions in the changelog. Version 3.13 restores semantic search on Smart Connections indexes built with the plugin's built-in model (BGE Micro by default), through the optional @huggingface/transformers package; see embedders.
Version 3.14 prepares undated notes through FDM before protected edits, preserves undated templates and excluded paths, and accepts Obsidian CRLF/LF normalization during preparation. FDM 1.6.0 is qualified; other date managers are not. See the 3.14.0 release notes.
Version 3.17 adds governed Base configuration (bases_config_patch_plan: filters, formulas, property settings, summaries and views of an existing Base) and every JSON Canvas option to the governed Canvas patch (file, link and group nodes, node fields, edge labels, colors and arrows); no Bridge change. Version 3.16 adds governed Base and Canvas creation: bases_create_plan and obsidian_canvas_create_plan create one new validated .base or .canvas file without ever overwriting, through two new Atomic Write Bridge 0.9.0 grants that are off by default. Install MCP 3.16.0 with Atomic Write Bridge 0.9.0 from the same Bridge bundle; see the 3.16.0 release notes. Version 3.15 adds governed note deletion to Obsidian's trash (off by default: Bridge grant allowNoteDeletes plus MCP_WRITE_MODE=full), the Bridge effect fence with obsidian_operation_close for uncertain operations, a shared note-name rule, Obsidian's native frontmatter format for governed writes, readable rotating logs, the checkpoint_wal maintenance action, opt-in ChatGPT result compatibility and an optional backend supervisor. Tools exposing responseMode now answer compact by default; request detailed (or tree / legacy where the tool offers it) for the previous shape. In , is hidden in favour of the governed deletion family. Versions 3.15.1 and 3.15.2 return Operon mutation receipts sooner and bound read retries after a mutation. Install MCP 3.15.x and Atomic Write Bridge 0.8.5 together, from the Bridge bundle of the same release. See the , and release notes.
Capability map
| Area | What the MCP provides | Main dependency |
|---|
| Notes | Read/search/direct edits plus governed note and Frontmatter operations | Vault; Local REST API + Atomic Write Bridge |
| Bases and Canvas | Queries, bounded writes, governed formulas and Canvas graph plans | Bases Bridge; Atomic Write Bridge |
| Tasks | Tasks-compatible Markdown plus 25 governed Operon tools | Operon Developer API V1 through the Bridge |
| Semantic search | Smart Connections index search | .smart-env + Ollama, OpenAI-compatible or built-in model query embedding |
| Runtime | Shared SQLite cache, health, maintenance and degraded modes | Local filesystem |
| External documents | Default-deny reads/handoff plus opt-in local move | Explicit root allowlist |
| Headless administration | Guarded metadata and filesystem operations | Copied or dedicated vault |
The canonical tool registry is documented in Tool Surface.
Runtime and transport
| Need | Recommended runtime / transport |
|---|
| Local agent | stdio proxy |
| Obsidian Desktop automation | live or hybrid |
| CI/server/synchronized copy | headless-readonly |
| Bounded writes on copied/dedicated vault | headless-guarded, then headless-filesystem |
| Same-machine HTTP | authenticated loopback HTTP |
| Remote HTTP | reviewed TLS reverse proxy + private network; pilot only |
Runtime answers what the backend can execute. It does not decide how many tools the model should see.
Tool surface profiles
| Need | Profile | Full live/hybrid size |
|---|
| General vault work | standard | 30 |
| Notes, tags, Bases and Canvas authoring | authoring | 54 |
| Tasks / Operon workflows | tasks | 36 |
| Complete daily workflows with governed preference | operational | 97 |
| Explicit complete, admin and specialized surfaces | full | 102 |
The counts above exclude three optional asset tools: the current local configuration exposes 100 operational and 105 full tools. The local launcher explicitly selects operational; the package-wide unspecified default remains standard.
In 3.0, an unspecified profile defaults to standard. smart_semantic_search is the only registered semantic-search name; the former smart_search and smart-search aliases have been removed. full remains an explicit opt-in for the complete active-runtime surface. bases_upsert_config is a full-only whole-Base compatibility path; legacy whole-file config writes are default-off, while normal authoring uses bounded Base creation/row writes plus the governed formula family.
Select the profile before tools/list:
node dist/stdio-proxy.js --tool-profile standard
HTTP profile routes:
/mcp/standard
/mcp/authoring
/mcp/tasks
/mcp/full
/mcp/operational
Unqualified /mcp now uses standard; /mcp/full remains the explicit complete route. See Tool Surface Profiles.
Quick start
Requirements:
- Node.js
>=22.12.0;
- Obsidian Desktop only for live features;
- capability-specific plugins listed below.
git clone https://github.com/optimikelabs/optimike-obsidian-mcp.git
cd optimike-obsidian-mcp
npm install
npm run build
node dist/stdio-proxy.js --tool-profile standard
Package binaries:
optimike-obsidian-mcp
optimike-obsidian-mcp-proxy
Minimal Codex configuration:
[mcp_servers.optimike-obsidian-mcp-stdio]
command = "node"
args = [
"/path/to/optimike-obsidian-mcp/dist/stdio-proxy.js",
"--tool-profile",
"standard"
]
[mcp_servers.optimike-obsidian-mcp-stdio.env]
OBSIDIAN_VAULT = "/path/to/vault"
OBSIDIAN_RUNTIME_MODE = "live"
OBSIDIAN_BASE_URL = "http://127.0.0.1:27123"
OBSIDIAN_API_KEY = "<local-rest-api-key>"
Keep real paths, API keys, journals and external-root configuration outside the repository and distributable vault content. To connect a private local runtime to ChatGPT without a public endpoint or a Chat On Steroids dependency, see ChatGPT through Secure MCP Tunnel.
Optional Obsidian integrations
Enable only the surfaces you use:
- Local REST API for live note, metadata and tag operations;
- bundled Bases Bridge for live Bases and governed formula CAS;
- bundled Optimike Atomic Write Bridge for governed Note replacement, body text patch, Frontmatter and Canvas
plan → apply → status → recover, governed note deletion, and governed Base and Canvas creation. MCP 3.16.x ships Atomic Write Bridge 0.9.0 (Base and Canvas creation need it; the other governed families accept 0.8.4 or later): deploy and roll back both as one pair;
- Smart Connections for the local semantic index;
- Operon Developer API V1 and bundled Optimike Operon Bridge 0.9.3 for governed task operations. Optimike MCP
3.9.1 certifies official Operon 3.9.3 against Developer API V1 with Operon CLI 1.2.0 and Local REST API 5.1.0; release admission follows the proportionate qualification policy, with the exact-SHA Pilot 2 gate for changed or unqualified paths. The public Developer API contract and additive workflow boundary did not drift from 3.6.2; Pilot 2 verifies native preview/apply, idempotent replay, stale-revision rejection, typed media, exact restoration and zero pending recovery. Future non-denied releases remain compatible-provisional until separately evidenced. The three bundled Bridges recover their Local REST routes after late startup or reload without restarting the MCP or changing write authorization. Their single verified release bundle preserves plugin settings and supports fenced rollback.
- Obsidian Tasks for Tasks-compatible Markdown parsing.
Operon mutations require the Bridge mutation setting plus:
OPERON_MUTATIONS_ENABLED=true
Stale Operon snapshots remain read-only. No Operon route falls back to raw Markdown or private APIs. Official adoption and Daily/Weekly routing negotiate their exact additive grant on first use, including after a cold MCP start; a pending or refused grant still fails closed. Operon owns every opaque sealed plan and same-plan recovery. Task Type and Task Image stay scalar, Task Gallery stays an ordered array, and __taskDataType is read-only. Full compatibility, certified/provisional versions, recovery semantics and current API gaps live in the Operon MCP contract and CLI / Developer API audit.
Operon 3.6.0 exposes the public periodic Task Workflow plan as metadata-only, without a pre-apply task-source path. The exact-SHA release canary negotiates and previews periodic operations but skips periodic applies with reason
public_task_source_projection_unavailable. This contains the destructive canary
without disabling runtime tools; upstream public path projection is a nonblocking follow-up, and no full periodic certification is claimed. Core startup, adoption, media, Frontmatter Date Manager, idempotence and restoration gates remain mandatory.
Governed operations
Governed Note replacement, body text patch, Frontmatter, Base formula and Canvas families are exposed atomically:
plan → apply → status → recover
After timeout or transport loss, call status before recover; never create a blind replacement mutation. Durable plans are not bound to the profile that created them.
If the client lost the opaque plan reference, call obsidian_list_pending_operations. The readonly cockpit lists only pending or uncertain governed Obsidian receipts from the live runtime's already-open journals, with the exact domain planRef and the next safe action. It never exposes targets, idempotency keys, content, hashes or backend bindings, and it never invokes status, apply or recovery. See Pending Operation Cockpit. Uncertain operations that nothing can settle are closed, after owner review, with obsidian_operation_close (Administrative closure).
External document roots
External roots are disabled by default. They are an authorization broker, not an index, sync engine or backup system.
external_handoff is transport-aware:
- local stdio returns a verified short-lived
local_path;
- authenticated direct HTTP may return an opt-in, identity-bound, single-use
http_ticket;
- neither delivery mode authorizes mutation or reveals the physical source path.
external_references_scan, external_move_plan and external_move_status are
diagnostic only. external_move_apply, external_move_rollback and any automatic mutating recovery are disabled on every platform until an audited native handle-relative mutation primitive exists; the runtime reason is
native_handle_relative_mutation_unavailable. The contract still preserves
redacted receipts, private SQLite snapshots, legacy-binding and stale session/binding checks, and exact-CAS evidence for a future implementation.
The MCP core does not embed PDF, Office or OCR engines. The caller owns binary extraction and verifies size and SHA-256.
See External Roots Setup.
Semantic search
smart_semantic_search is the canonical semantic-search tool. It searches the local Smart Connections index. Query embedding can remain local through Ollama, use an OpenAI-compatible provider, or reuse the Smart Connections built-in model (BGE Micro by default) once the optional @huggingface/transformers package is installed. See embedders.
See Operations for providers and cache behavior.
Verification
npm run build
npm run test:runtime
npm run test:governed-note-replace-mcp
npm run check:operon
npm run test:external-roots
npm run test:docs
npm run test:package
npm run audit:production
Runtime suites use disposable vaults and run in Linux/Windows CI.
Documentation
Credits
Created by Optimike — Mickaël Ahouansou.
License
See LICENSE.
