# Optimike Obsidian MCP

[![Latest release](https://img.shields.io/github/v/release/optimikelabs/optimike-obsidian-mcp?display_name=tag&sort=semver)](https://github.com/optimikelabs/optimike-obsidian-mcp/releases/latest)

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

![Overview of Optimike Obsidian MCP between agent clients, Obsidian and governed external documents](docs/assets/readme/overview.en.svg)

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](docs/cycle-20260920/CODEX-FINALISATION.md) and [bounded roadmap](docs/cycle-20260920/ROADMAP.md). 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](docs/mcp-2026-dual-stack.md) and [Skills publication contract](docs/mcp-skills.md). 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](CHANGELOG.md#3120---2026-10-08). 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](README_EMBEDDERS.md).

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](docs/releases/3.14.0.md).

Version 3.17 adds [governed Base configuration](docs/governed-base-config.md) (`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](docs/governed-file-create.md): `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](docs/releases/3.16.0.md). Version 3.15 adds [governed note deletion](docs/governed-note-delete.md) to Obsidian's trash (off by default: Bridge grant `allowNoteDeletes` plus `MCP_WRITE_MODE=full`), the Bridge effect fence with [`obsidian_operation_close`](docs/administrative-closure.md) for uncertain operations, a shared [note-name rule](docs/note-name-rules.md), Obsidian's native frontmatter format for governed writes, readable rotating logs, the `checkpoint_wal` maintenance action, opt-in [ChatGPT result compatibility](docs/chatgpt-secure-tunnel.md) and an optional [backend supervisor](docs/backend-supervision.md). 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](docs/releases/3.15.0.md), [3.15.1](docs/releases/3.15.1.md) and [3.15.2](docs/releases/3.15.2.md) 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](docs/obsidian_mcp_tools_spec.md).

## 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`:

```bash
node dist/stdio-proxy.js --tool-profile standard
```

HTTP profile routes:

```text
/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](docs/tool-surface-profiles.md).

## Quick start

Requirements:

- Node.js `>=22.12.0`;
- Obsidian Desktop only for live features;
- capability-specific plugins listed below.

```bash
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:

```text
optimike-obsidian-mcp
optimike-obsidian-mcp-proxy
```

Minimal Codex configuration:

```toml
[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](docs/chatgpt-secure-tunnel.md).

## Optional Obsidian integrations

Enable only the surfaces you use:

- [Local REST API](https://github.com/coddingtonbear/obsidian-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](docs/bridge-packaging.md#proportionate-release-qualification), 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](docs/bridge-lifecycle.md) without restarting the MCP or changing write authorization. Their [single verified release bundle](docs/bridge-packaging.md) preserves plugin settings and supports fenced rollback.
- **Obsidian Tasks** for Tasks-compatible Markdown parsing.

Operon mutations require the Bridge mutation setting plus:

```text
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](docs/operon-mcp-contract.md) and [CLI / Developer API audit](docs/operon-cli-audit.md).

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:

```text
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](docs/operation-cockpit-p5.md). Uncertain operations that nothing can settle are closed, after owner review, with `obsidian_operation_close` ([Administrative closure](docs/administrative-closure.md)).

## 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](docs/external-roots-setup.md).

## 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](README_EMBEDDERS.md).

See [Operations](OPERATIONS.md) for providers and cache behavior.

## Verification

```bash
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](docs/installation-options.md) : profile, shared HTTP quota and optional FDM integration.
- [Documentation hub](docs/README.md)
- [Tool Surface Profiles](docs/tool-surface-profiles.md)
- [Tool Surface](docs/obsidian_mcp_tools_spec.md)
- [Runtime Capability Matrix](docs/runtime-capability-matrix.md)
- [Runtime Capability Doctor](docs/capability-doctor.md)
- [Bridge Lifecycle Recovery](docs/bridge-lifecycle.md)
- [Bridge Bundle, Upgrade and Rollback](docs/bridge-packaging.md)
- [MCP Routing Guide](docs/mcp-routing-guide.md)
- [Tool Routing Evaluation and Profile Decision](docs/tool-routing-evaluation-p6.md)
- [Operon MCP Contract](docs/operon-mcp-contract.md)
- [External Roots Setup](docs/external-roots-setup.md)
- [Headless Server Profile](docs/headless-server-profile.md)
- [Gateway Compatibility](docs/gateway-compatibility.md)
- [ADR Index](docs/adr/README.md)

## Credits

Created by **Optimike — Mickaël Ahouansou**.

## License

See [LICENSE](LICENSE).