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;

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

• Kairélys 2.6.3+ / compatible Operon and the bundled Optimike Operon Bridge: governed live task operations;

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

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

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