Obsidian MCP 服务

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 operational, obsidian_delete_note 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 3.15.0, 3.15.1 and 3.15.2 release notes.

Capability map

The canonical tool registry is documented in Tool Surface.

Runtime and transport

Runtime answers what the backend can execute. It does not decide how many tools the model should see.

Tool surface profiles

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

• Installation choices : profile, shared HTTP quota and optional FDM integration.
• Documentation hub
• Tool Surface Profiles
• Tool Surface
• Runtime Capability Matrix
• Runtime Capability Doctor
• Bridge Lifecycle Recovery
• Bridge Bundle, Upgrade and Rollback
• MCP Routing Guide
• Tool Routing Evaluation and Profile Decision
• Operon MCP Contract
• External Roots Setup
• Headless Server Profile
• Gateway Compatibility
• ADR Index

Credits

Created by Optimike — Mickaël Ahouansou.

License

See LICENSE.