obsidian-tc

# obsidian-tc

> Obsidian Turbocharged — governed, agent-ready vault access over MCP.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
![Status: Shipped v1.30.1](https://img.shields.io/badge/Status-Shipped_v1.30.1-success)

```bash
npm install -g obsidian-tc      # Node >= 24 or Bun >= 1.1
```

Also ships as a Docker image (`ghcr.io/the-40-thieves/obsidian-tc`), a one-click `.mcpb` bundle, and standalone binaries.

Since v5.0 (2026-07-24), the Local REST API plugin ships its own built-in MCP server — 18
tools at `https://127.0.0.1:27124/mcp/` for vault CRUD, search, and commands. obsidian-tc adds
three things it doesn't have: **governed writes** (folder ACLs, human-in-the-loop confirmation,
compare-and-swap, an audit log), **fused retrieval** (BM25 + vector + graph, RRF-fused and
reranked), and **memory that lives in the vault** — episodes, activation decay, and explicit
forgetting, under the same ACL as every other write.

The fastest way to try it, no install step and no config file:

```sh
npx obsidian-tc /path/to/vault
```

Lexical search and every note tool work immediately; semantic and graph-seeded retrieval need
an embeddings backend (Ollama by default), which is the upgrade a config file buys you.

## TC Bridge: the companion Obsidian plugin

If you arrived here from Obsidian's plugin browser, this section is the part about you. The
directory listing for **TC Bridge** points at this repository because the plugin lives in it, but
the plugin is a small optional bridge, not the server described on the rest of this page.

TC Bridge extends the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)
plugin with namespaced endpoints that the obsidian-tc server calls for features that only exist
inside a running Obsidian: command-palette dispatch, Templater, Dataview and Datacore queries,
Tasks, QuickAdd, Omnisearch, Excalidraw, Metadata Menu, MakeMD spaces, daily notes, OCR via Text
Extractor, Obsidian Git, and Remotely Save. Every filesystem-level feature of the server (governed
writes, search, memory) works without it.

- **Install and enable Local REST API first.** TC Bridge registers its routes on that plugin's
  server and reuses its bearer-token auth. It opens no port of its own and is desktop-only.
- **The plugin is not the server.** The folder ACLs, human-in-the-loop confirmations and retrieval
  described below run in the obsidian-tc process, which you install and run separately (see
  [Quick start](#quick-start)). To reach the bridges, the server's per-vault config needs
  `restApiUrl` and `restApiKey`; the walkthrough is
  [docs/QUICKSTART.md, step 6](./docs/QUICKSTART.md#6-optional-light-up-the-plugin-bridges-live-mode).
- **The Local REST API key is a vault root password.** The bridge routes run with the same
  authority as that plugin's own endpoints, so read the
  [companion plugin trust boundary](./SECURITY.md#companion-plugin-trust-boundary) before handing
  the key to any agent.
- **Formerly "Obsidian Turbocharged" (id `obsidian-tc`).** That id is retired; settings migrate on
  first load and the old id's final release only shows a pointer here. Details in
  [packages/plugin/README.md](./packages/plugin/README.md).

## Why this exists

An AI agent with raw filesystem access to your Obsidian vault can do real damage: overwrite years of notes, delete the wrong folder, read the journal you never meant to expose, or quietly leak plugin API keys sitting in `.obsidian/`. Most Obsidian MCP servers hand an agent that access with little more than an API key between it and everything you have written.

obsidian-tc gives agents **governed** access instead. Every tool call — no exceptions — runs through one dispatch pipeline: auth → scopes → folder ACL → read-only kill switch → idempotency → throttle → human-in-the-loop confirmation → handler → response governor → audit log. You decide which folders an agent can read, write, or delete (per vault, per caller); destructive operations fail closed until a human approves them; and every invocation is audited on a best-effort basis (an audit-store write failure surfaces in `server_health` and is never swallowed silently, but it does not block the call — observability must never break dispatch).

New here? Start with the [5-minute quickstart](./docs/QUICKSTART.md) or the [threat model and design rationale](./docs/WHY.md).

## The interface: 3 tools, ~163 governed capabilities

By default the server advertises just **three meta-tools** instead of a wall of 150:

- **`find_capability`** — BM25 search over the caller-visible capability catalog ("how do I move a note?")
- **`describe_capability`** — one capability's schema, required scopes, and safety hints
- **`call_capability`** — invoke the named capability; the call routes through the same auth/scope/ACL/HITL/idempotency/throttle pipeline as a direct call, and the target's own schema validates the arguments

This keeps agent context lean while the full surface — 163 tools across 31 domains — stays reachable, and every tool remains directly callable by name. `toolFacade.mode` selects the shape: `triad` (default), `domain` (~a dozen domain meta-tools like `notes`, `search`, `vault`), or `flat` (the full advertised surface, the pre-facade behavior). The facade is boundary-only: no gate is ever bypassed, whichever mode you pick.

<!-- BEGIN GENERATED: tools-summary -->
**163 governed capabilities**, grouped by access scope.

**read** (96) — `audit_provenance`, `bundle_files`, `bundle_folder`, `diagnose_retrieval`, `episode_stats`, `eval_dataview_field`, `explain_answer`, `find_link_cycles`, `find_notes_by_property`, `find_notes_by_tag`, `find_orphans`, `find_unresolved_links`, `gap_report`, `generate_uri`, `get_attachment`, `get_backlinks`, `get_entity`, `get_index_status`, `get_link_strength`, `get_note_tags`, `get_outgoing_links`, `get_periodic_note`, `get_session_traces`, `get_vault`, `git_diff`, `git_log`, `git_status`, `graph_centrality`, `graph_communities`, `graph_path_between`, `knowledge_challenge`, `knowledge_get_critical`, `knowledge_search`, `list_attachments`, `list_bookmarks`, `list_capture_queue`, `list_commands`, `list_contradictions`, `list_goals`, `list_kanban_boards`, `list_notes`, `list_periodic_notes`, `list_properties`, `list_quickadd_actions`, `list_snapshots`, `list_tags`, `list_tasks`, `list_templates`, `list_vaults`, `list_workspaces`, `makemd_list_spaces`, `makemd_query`, `note_exists`, `note_quality_report`, `ocr_attachment`, `ocr_bulk`, `plur_get`, `plur_recall`, `plur_recall_hybrid`, `plur_similarity_search`, `query_base`, `query_canvas`, `query_datacore`, `query_entity_graph`, `read_base`, `read_canvas`, `read_excalidraw`, `read_frontmatter`, `read_kanban_board`, `read_metadata_fields`, `read_note`, `read_notes`, `read_property`, `read_snapshot`, `reflect`, `remotely_save_status`, `resolve_daily_note`, `search_dql`, `search_jsonlogic`, `search_omnisearch`, `search_regex`, `search_semantic`, `search_text`, `search_vault`, `server_health`, `session_bootstrap`, `snapshot_note`, `suggest_links`, `tasks_filter`, `validate_dql`, `vault_context`, `vault_graph_search`, `vault_health_score`, `work_episode_chain`, `work_episodes`, `work_search`

**write** (46) — `add_bookmark`, `add_kanban_card`, `add_observation`, `add_tag`, `append_note`, `append_to_periodic_note`, `close_goal`, `commit_capture`, `copy_note`, `create_base`, `create_canvas`, `create_entity`, `create_excalidraw`, `create_periodic_note`, `end_session`, `enqueue_capture`, `execute_template`, `find_or_create_periodic_note`, `format_table`, `git_stage`, `insert_table_column`, `insert_table_row`, `link_entities`, `move_kanban_card`, `open_workspace`, `patch_note`, `prune_hub_links`, `record_retrieval_feedback`, `remotely_save_trigger`, `remove_tag`, `rename_entity`, `restore_note`, `rewrite_link`, `save_workspace`, `set_goal`, `sort_table_by_column`, `start_session`, `unlink_entities`, `update_base`, `update_canvas`, `update_excalidraw`, `update_frontmatter`, `update_task`, `work_forget`, `work_result`, `write_note`

**delete** (6) — `delete_attachment`, `delete_entity`, `delete_note`, `move_attachment`, `move_note`, `remove_bookmark`

**bulk** (3) — `bulk_create_notes`, `bulk_move_notes`, `bulk_set_property`

**execute** (3) — `execute_command`, `git_commit`, `trigger_quickadd`

**admin** (9) — `add_vault`, `get_metrics`, `get_server_config`, `index_vault`, `inspect_acl`, `inspect_visibility`, `refresh_plugin_capabilities`, `reload_vault`, `reset_vault_cache`
<!-- END GENERATED: tools-summary -->

## What it is

obsidian-tc is a comprehensive Model Context Protocol (MCP) server for [Obsidian](https://obsidian.md), designed for both humans and autonomous agents. Multi-vault native. Pluggable embeddings. Works with local Ollama or cloud models.

Three pillars:

1. **Broad.** 163 tools covering the meaningful Obsidian operations — including native Bases (`.base`) support with a real expression-DSL evaluator, GraphRAG retrieval, a quarantined work-memory tier, and composite context calls — the broadest open-source Obsidian MCP surface we know of (surveyed 2026-07).
2. **Governed by default.** JWT auth (HS256 or asymmetric RS256/ES256/EdDSA via a local JWKS with `kid` rotation), folder ACLs (per vault), read-only kill switch, human-in-the-loop elicit on destructive operations, compare-and-swap on writes, idempotency keys, bulk throttling.
3. **Observable from day one.** OpenTelemetry traces, Prometheus metrics, structured CloudEvents emission on every tool call — all opt-in export streams that fail soft.

Beyond Tools, the server exposes your vault as MCP **Resources** (`resources/list` + `resources/read` over `obsidian-tc://<vault>/<path>` URIs, read-scope and folder-ACL enforced) and a set of built-in **Prompts** (`prompts/list` + `prompts/get`).

## Status

✅ **Shipped — v1.30.1.** Published to npm as provenance-signed packages, with a contain