Obsidian Turbocharged README

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. A full tool surface across every domain (all visible by default; a smaller set with opt-in profile: "core"), via a 3-tool discovery facade plus the standard search/fetch pair, listed in the tool catalog. 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 for which install methods it reaches.

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:

• 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 may be all you need — see the full comparison.
• Zero setup, source checkouts only. The vault is read 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 server is 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.33.1, 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.

Every capability is a governed tool with declared access scopes. Read tools (read_note, search_vault, get_backlinks, ...) never mutate the vault. Write tools cover whole-note and partial edits: write_note, append_note, patch_note (heading- and block-anchored edits), update_frontmatter, tag and link maintenance. Separate scope classes gate delete and move (delete_note, move_note), bulk operations (bulk_set_property), execute (execute_command) and admin (add_vault, reload_vault). The complete, always-current list, grouped by access scope and generated from the tool registry, is the tool catalog.

The interface: five tools, every governed capability

By default the server advertises just five tools instead of a wall of 164: three meta-tools, find_capability, describe_capability, call_capability (invoke by name, same pipeline as a direct call), plus the standard search and fetch tools ChatGPT deep research needs. toolFacade.mode selects triad (default), domain or flat (a superseded auto also exists) — boundary-only, no gate bypassed. Per-client advice: MCP clients.

Install in Claude Code, Cursor, VS Code

Claude Code plugin (launches npx -y obsidian-tc, asks for your config file path on enable):

claude plugin marketplace add The-40-Thieves/obsidian-tc
claude plugin install obsidian-tc@the-40-thieves

Grok Build and Muse Code (1.4.0+) read the same marketplace; details in Installation.

Install in VS Code Insiders

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. For claude.ai and ChatGPT (remote HTTP), see distribution.

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.