obsidian-tc

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

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:

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 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). To reach the bridges, the server's per-vault config needs restApiUrl and restApiKey; the walkthrough is docs/QUICKSTART.md, step 6.
• 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 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.

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 or the threat model and design rationale.

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.

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

What it is

obsidian-tc is a comprehensive Model Context Protocol (MCP) server for Obsidian, 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