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.

Capability map

The canonical tool registry is documented in Tool Surface.

Related MCP server: obsidian-local-mcp

Runtime and transport

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

Tool surface profiles

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

Unqualified /mcp now uses standard; /mcp/full remains the explicit complete route. See Tool Surface Profiles.

Quick start

Requirements:

• Node.js >=22.7.5;

• 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.

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, Frontmatter and Canvas plan → apply → status → recover;

• Smart Connections for the local semantic index;

• Operon Developer API V1 and bundled Optimike Operon Bridge for governed task operations;

• 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. Full compatibility, certified/provisional versions, recovery semantics and current API gaps live in the Operon MCP contract and CLI / Developer API audit.

Governed operations

Governed Note, 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.

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.

A separate local-stdio transaction can move one regular file within the same configured root and repair exact ÉLYSIA references. It requires inventory, a durable plan, explicit write gates, hash/CAS preconditions, journaling and rollback. It is not exposed over direct HTTP and does not add generic create, replace, delete, upload or sync.

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 or use an OpenAI-compatible provider.

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

• Documentation hub

• Tool Surface Profiles

• Tool Surface

• Runtime Capability Matrix

• MCP Routing Guide

• Operon MCP Contract

• External Roots Setup

• Headless Server Profile

• Gateway Compatibility

• ADR Index

Credits

Created by Optimike — Mickaël Ahouansou.

License

See LICENSE.