Optimike Obsidian MCP

French version: README.fr.md · Documentation hub: docs/README.md Operations: OPERATIONS.md Security: SECURITY.md

Optimike Obsidian MCP gives MCP clients a governed operational surface over an Obsidian vault. It combines live Desktop operations, resilient headless modes, structured task and Bases support, semantic search, runtime observability, and explicitly governed access to configured documents outside the vault.

Capability map

The current tool registry is documented in Tool Surface. Availability varies by runtime mode; use the Runtime Capability Matrix before enabling writes.

Related MCP server: obsidian-mcp-pro

Choose a profile

The Node server must never be exposed directly to the public internet. See Security and the HTTP delivery ADR.

Quick start from source

Requirements:

• Node.js >=22.7.5;

• Obsidian Desktop only when using live Desktop 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

For a package install, the explicit proxy binary is optimike-obsidian-mcp-proxy. The legacy optimike-obsidian-mcp binary still starts the backend directly.

Minimal Codex configuration:

[mcp_servers.optimike-obsidian-mcp-stdio]
command = "node"
args = ["/path/to/optimike-obsidian-mcp/dist/stdio-proxy.js"]

[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 and external-root configurations outside the repository and outside distributable vault content.

Optional Obsidian integrations

Enable only the surfaces you use:

• Local REST API: live note, metadata and tag operations;

• bundled Bases Bridge (REST): live .base operations;

• bundled Optimike Atomic Write Bridge: opt-in SHA-256 compare-and-replace for the internal note-operation pilot;

• Smart Connections: semantic index under .smart-env;

• Operon Developer API V1 and the bundled Optimike Operon Bridge: governed live task operations through the official Developer API V1;

• Kairélys compatibility remains available as a bounded legacy/rollback path, not as the production owner;

• Obsidian Tasks: canonical Tasks parsing and configuration.

Operon apply requires two explicit opt-ins:

Optimike Operon Bridge setting: Allow task mutations
OPERON_MUTATIONS_ENABLED=true

Stale Operon snapshots remain read-only. Atomic note replacement has a separate default-off bridge setting and does not require Operon's Developer API grant.

The MCP exposes a curated agent surface rather than every Operon CLI function. Native diagnostics, finder/resolve, bounded relationships/context and timer state are available as read-only tools. Dedicated relationship and recurrence writes use official sealed preview/apply plans; destructive and operator commands stay in the CLI. Agents use MCP because it adds bounded schemas, least-privilege capability checks, dry-run, revision locking, durable idempotency, postflight verification and exact-plan recovery. A generic CLI passthrough would bypass those guarantees. See the Operon MCP contract and Operon CLI / Developer API audit. Transition apply is available through the Bridge. Elevated or destructive plans still require fresh confirmation in the owning Obsidian vault window and fail closed after 45 seconds when no confirmation can be presented.

Compatibility note: the adapter negotiates Operon Developer API V1 with contractVersion: 1 and runtimeApi: 1. Versions in the explicit certified set report certified; unknown non-denied versions exposing the accessor report compatible-provisional. Live use still requires developerApi, ok, index.ready, and the exact capability. Missing capabilities fail closed only for affected tools; known regressions remain denied. Operon 3.2.0 remains the earlier certified pilot baseline. Modified-time frontmatter settlement and multi-window consent were merged upstream before these releases. Saved-filter execution is available through the additive task-workflow Developer API after an exact grant, but the official API does not expose the saved-filter catalog: callers must supply an exact filterSetId obtained from Operon's UI/configuration or an operator workflow. Adoption remains unavailable on the official Developer API. Operon 3.3.0 passed the complete live pilot and remains admitted as compatible-provisional by the contract-first policy rather than a product-version allowlist. Operon still omits the declarative Settings renderer for Developer API grant controls; the fix is tracked in #145 and #146. No MCP route falls back to Markdown or private APIs. Implicit File Task renames remain tracked in #139, and the unscoped transition edge case remains tracked in #99 and #101.

External document roots

External roots are disabled by default. Their ordinary reads and handoffs form a default-deny authorization broker, not an external index, sync engine or backup system.

The same external_handoff tool selects a transport-aware delivery:

• 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 discloses the physical source path or authorizes a mutation.

One deliberately narrow mutation exists outside the handoff path: local stdio through headless-filesystem on a copied or dedicated vault can move or rename one regular file within the same opted-in root and repair exact ÉLYSIA references. It requires an inventory and durable plan, explicit write gates, hash/CAS preconditions, a journal and compensating rollback. It is not exposed over direct HTTP and does not add create, replace, delete, upload or sync.

The MCP core does not embed PDF, Office or OCR engines. The calling client owns binary extraction and must verify size and SHA-256.

Start with External document roots — setup and operations.

Semantic search

smart_semantic_search searches a local Smart Connections index. Query embedding can remain local through Ollama or use OpenAI, depending on operator configuration. A configured OpenAI provider therefore makes this tool open-world even though the indexed vault data remains local.

See Operations for provider configuration and cache behavior.

Verification

npm run build
npm run test:runtime
npm run check:operon
npm run test:external-roots
npm run test:docs
npm run test:package
npm run audit:production

The runtime suites use disposable vaults and include Linux/Windows CI coverage. For production-like validation, keep the shared cache database outside the real synced vault.

Documentation

• Start here by audience and task: Documentation hub

• Runtime and maintenance: OPERATIONS.md

• Security and deployment boundary: SECURITY.md

• Current tools: Tool Surface

• Runtime modes: Runtime Capability Matrix

• Agent routing: MCP Routing Guide

• Operon tools and guarantees: Operon MCP Contract

• Operon surface and CLI routing: Operon CLI / Developer API audit

• Headless deployment: Headless Server Profile

• Linux headless multi-client pilot: Pilot and capability matrix

• OSS gateway integration: Gateway Compatibility

• External documents: External Roots Setup

• Architecture decisions and status: ADR Index

• Public ÉLYSIA task profile: profiles/elysia-tasks/README.fr.md

Credits

Created by Optimike — Mickaël Ahouansou.

License

See LICENSE.