obsidian-tc

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

What it is

obsidian-tc is a governed, agent-ready Model Context Protocol server for Obsidian vaults, for humans and agents alike. Instead of raw filesystem access to years of notes, every tool call runs through one pipeline — auth, folder ACLs, a read-only kill switch, HITL confirmation on destructive ops, and an audit log. It also adds fused retrieval (full-text, vector, graph) and a memory tier — episodes, decay, forgetting — living inside your vault under that same ACL. 163 tools across 31 domains (all visible by default; 97 with opt-in profile: "core"), via a 3-tool facade. Pitch: docs/WHY.md.

60-second start

No install:

npx obsidian-tc /path/to/vault

Every note tool and lexical search work immediately. Semantic search defaults to a bundled embedder — see When NOT to use below for which install methods it reaches today.

For multi-vault, auth, or ACLs, use a config file:

npm install -g obsidian-tc
obsidian-tc ./obsidian-tc.config.json   # Node >= 24 or Bun >= 1.1

Also ships as a Docker image, .mcpb bundle, and standalone binaries. More: docs/QUICKSTART.md.

When NOT to use obsidian-tc

Honest guidance — this is a heavier product than most alternatives:

• Smallest possible footprint, read-only access, or no MCP at all. A single trusted human over one vault, a read-only wrapper, or the Obsidian URI/Local REST API plugin directly may be all you need — see the full comparison. This mostly pays off with autonomous or multi-agent access.
• Zero setup, source checkouts only for now. The vault is read directly off disk; semantic search defaults to a bundled offline embedder; npm/Docker need an explicit provider until published — see Embeddings.
• Zero-config trades away auth/ACLs. obsidian-tc /path/to/vault boots with auth off, no folder ACL — fine only because it's local-only; governance is opt-in. Detail: SECURITY.md.
• AGPL-3.0's network-copyleft terms. Not permissive; a commercial license may exist — see License.
• Single-maintainer project.
• Everything inside Obsidian, or vault-independent memory. See the comparison above.

Migrating from another MCP server: docs/CUTOVER.md.

How it compares

Most Obsidian MCP projects are vault-access servers, retrieval engines, or memory engines, rarely more than one. obsidian-tc is the only one we know of that is all three, with memory living in the vault under the same ACL as every other write. Full 9-project table and "where the others win".

More

TC Bridge: the companion Obsidian plugin

If you arrived here from Obsidian's plugin browser: the TC Bridge listing points here because the plugin lives in this repo, but it's a small optional bridge, not the server described above. It extends Local REST API with endpoints for Obsidian-only features (Templater, Dataview, Tasks, Excalidraw, Git, Remotely Save). Every filesystem-level feature works without it.

• Install Local REST API first; TC Bridge reuses its bearer-token auth, desktop-only. The plugin is not the server — governance/retrieval run in the obsidian-tc process, installed separately (60-second start); reaching the bridges needs restApiUrl/restApiKey in the vault config (step 6). That key is a vault root password — read the trust boundary first.
• Formerly "Obsidian Turbocharged." Settings migrate on first load — details in packages/plugin/README.md.

Status

Shipped — v1.31.3, published to npm as provenance-signed packages, container image on GHCR. Milestones: Roadmap; releases: CHANGELOG.md.

Retrieval changes are measured, not asserted: a statistical ship rule gates every ranking change against a private golden set. Headline figures once on this README were withdrawn 2026-08-07 as unreproducible — full account and a public-corpus result since: docs/EVALUATION.md.

Architecture

Polyglot monorepo:

Dispatch-pipeline and package-layout detail: ARCHITECTURE.md.

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

The interface: 3 tools, ~163 governed capabilities

By default the server advertises just three meta-tools instead of a wall of 163: find_capability, describe_capability, call_capability (invoke by name, same pipeline as a direct call). toolFacade.mode selects triad (default), domain, flat, or auto — boundary- only, no gate bypassed.

Install in Cursor / VS Code

Or by hand — Cursor (mcpServers) / VS Code (servers), same object: {"command": "npx", "args": ["-y", "obsidian-tc"], "env": {"OBSIDIAN_TC_CONFIG": "/ABS/config.json"}}. A .mcpb bundle (bun run bundle) also installs into Claude Desktop / other MCPB hosts.

Docs

• docs/QUICKSTART.md — install to first governed write, ~5 min
• docs/WHY.md / SECURITY.md — threat model, governance
• docs/CUTOVER.md — migrating from another Obsidian MCP server
• docs/EVALUATION.md — how retrieval changes are measured
• ARCHITECTURE.md — dispatch pipeline, package layout
• Docs site: https://obsidian-tc.the40thieves.io (full comparison under Getting Started)

Trademark

obsidian-tc is independent and community-built, not affiliated with or endorsed by Obsidian or its maker, Dynalist Inc. "Obsidian" is a Dynalist Inc. trademark, used only nominatively. Official app: obsidian.md.

License

AGPL-3.0-only. See LICENSE and the licensing FAQ; a commercial exception may exist — open a discussion. Contributions under the DCO; sign-off in CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md / Code of Conduct. Security: SECURITY.md.