A
licenseA
qualityA
maintenanceThe most feature-complete MCP server for Obsidian vaults. 23 tools and 3 resources for search, read, write, tags, link analysis, graph traversal, and canvas support.
41
109 npm
32
MIT
obsidian-tc
Discover and invoke the full governed Obsidian vault tool surface — 164 capabilities behind a 3-tool facade — over MCP.
Find capabilities:
find_capabilitydoes natural-language search over the whole catalog (name + one-line summary); read theobsidian-tc://catalogresource to enumerate everything grouped by domain.Inspect before calling:
describe_capabilityreturns a capability's full input schema, required access scopes, and safety hints (read-only / destructive).Run anything safely:
call_capabilityinvokes a capability by name; it routes through the same pipeline as a direct call — auth, folder ACLs, read-only kill switch, HITL confirmation on destructive ops, idempotency, rate limits, audit log — and validates args against the target's schema.Read the vault: read notes, search vault (full-text / lexical), get backlinks, and other non-mutating reads.
Write and edit: whole-note and partial edits —
write_note,append_note,patch_note(heading/block-anchored),update_frontmatter, plus tag and link maintenance.Destructive and structural ops (separately scoped): delete, move, bulk property changes (
bulk_set_property),execute_command, and admin likeadd_vault/reload_vault.Retrieval and memory: fused retrieval (full-text, vector, graph) and an in-vault memory tier — episodes, decay, forgetting — under the same ACL as every write.
Optional plugin bridges: reach Obsidian-only features (Templater, Dataview, Tasks, Excalidraw, Git, Remotely Save) via the TC Bridge/Local REST API.
Facade modes:
triad(default 3 tools),domain, orflat— boundary-only, no gate bypassed.
Allows creating, reading, and updating Excalidraw diagrams stored in the vault.
Provides Git operations on the vault repository, including status, diff, log, staging, and commit.
Provides governed access to Obsidian vaults, allowing agents to read, write, search, and manage notes, attachments, properties, canvases, and vault metadata with folder ACLs, human-in-the-loop confirmation, and audit logging.
Uses Ollama as an embeddings backend to enable semantic and graph-seeded retrieval across vault notes.
Emits OpenTelemetry traces for tool calls, enabling distributed tracing and observability of server operations.
Exposes Prometheus metrics for monitoring server performance, tool usage, and health.
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.
Related MCP server: Synapse
60-second start
No install:
npx obsidian-tc /path/to/vaultEvery 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.1Also 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/vaultboots 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".
Tools | Group | What it's for | |
obsidian-tc | full surface (3-tool facade) | all three | governed access + retrieval + in-vault memory |
18 | access | Obsidian's own built-in MCP server; one bearer key, no ACL | |
~35 | memory | entities/relations in a separate, portable markdown KB |
More
TC Bridge · Status · Architecture · The interface · Claude Code / Cursor / VS Code · Docs · Trademark · License · Contributing
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/restApiKeyin 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:
Package | Language | Purpose |
| TypeScript (Bun) | MCP layer, auth, routing, tools, plugin bridges |
| TypeScript | Companion Obsidian plugin extending Local REST API |
| TypeScript | Shared Zod schemas and types |
| Rust (napi-rs) | Optional acceleration, pure-JS fallback |
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-thievesGrok Build and Muse Code (1.4.0+) read the same marketplace; details in Installation.
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.
Available Tools
3 toolscall_capabilityCall capabilityA
Invoke a capability by name with its arguments. Routes into the same authorization, ACL, HITL, idempotency, and rate-limit pipeline as a direct tool call, so every safety gate applies and the target's own schema validates the arguments.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | ||
| name | Yes |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description proactively discloses that the call goes through authorization, ACL, HITL, idempotency, and rate-limit pipelines, which is important behavioral context. It does not mention output/return behavior or potential side effects, but the lack of output schema and the generic 'invoke' wording keep this from being misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no redundant or extraneous information. It delivers key behavioral details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic invocation tool, the description covers the main purpose, safety pipeline, and argument validation. It does not mention how to discover capability names or what the return value looks like, but sibling tool names and the absence of an output schema reduce the need for that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides names and types for the two parameters, and the description adds that 'name' is the capability name and 'args' are its arguments. There are no detailed parameter descriptions, but the description adequately maps the parameters to their intended roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool invokes a capability by name with its arguments, which is a specific action distinct from the sibling find/describe tools. It also explains the routing and safety pipeline, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how the tool behaves but does not explicitly state when to use this tool versus the sibling find_capability or describe_capability. The sibling names imply the distinction, but the description itself lacks direct usage guidance for choosing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe_capabilityDescribe capabilityARead-only
Return the full input schema, required scopes, and safety hints (read-only / destructive) for a single capability by name.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions returning safety hints but does not explicitly state that this operation itself is read-only. Annotations already declare readOnlyHint true and destructiveHint false, so no contradiction exists; the description adds some context but not substantial side-effect detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear, direct sentence with no wasted words. The essential information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully summarizes the return content: full input schema, required scopes, and safety hints. It could mention error cases or output format details, but for a simple describe operation it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'name' is described as identifying 'a single capability by name,' which gives it meaning beyond the bare string schema. It does not specify format or uniqueness, but for a single simple parameter it is adequately explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Return' and a specific resource: the full input schema, required scopes, and safety hints for a single capability by name. This distinguishes it from siblings like call_capability and find_capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when you need metadata for a named capability, but does not explicitly contrast with call_capability or find_capability or state when one would choose this over them. The purpose is clear, but usage guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_capabilityFind capabilityARead-only
Search this server's full tool catalog by natural-language query and return the best-matching capabilities (name + one-line summary). Use it to discover which tool to call, then describe_capability for its schema and call_capability to run it. To enumerate the whole caller-visible catalog grouped by domain instead of searching it, read the obsidian-tc://catalog resource.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| query | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only search operation (search and return) without any mention of modifications or side effects. Since no annotations are provided, the description carries the full burden. It is clear that this is a non-destructive query, though it does not explicitly state that it makes no changes to the system.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, consisting of two sentences that front-load the primary action and then provide essential guidance. It avoids redundancy and includes all necessary information without verbose explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description provides sufficient context to use it correctly. It explains the purpose, the input parameters, and the relationship to sibling tools, making it self-contained for an agent. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names and types without descriptions. The description adds meaning to 'query' by referring to 'natural-language query' and to 'limit' by indicating 'best-matching capabilities' (implying a cap on results), but it does not explain the required nature, the range of limit, or any other constraints. The description partially compensates for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a search over the server's tool catalog, specifying the input (natural-language query) and output (best-matching capabilities with name and one-line summary). It distinguishes itself from sibling tools by focusing on discovery rather than schema retrieval or execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (to discover which tool to call) and provides a clear next-step workflow: use describe_capability for schema and call_capability for execution. It also mentions an alternative for enumeration (reading the catalog resource), leaving no ambiguity about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
call_capability - First observed
describe_capability - First observed
find_capability
TDQS
A4.4/5.0
Scored across 3 tools
Disambiguation5/5
Each tool has a clearly distinct role: find_capability discovers, describe_capability inspects, call_capability executes. There is no overlap or ambiguity between them.
Naming Consistency5/5
All three tools follow the same verb_noun snake_case pattern with a consistent capability-related noun. The naming is uniform and predictable.
Tool Count5/5
Three tools is well-scoped for a capability routing server; each tool covers one essential step in the discover-describe-invoke workflow. No redundant tools exist.
Completeness5/5
The tool set covers the full workflow of finding, understanding, and calling a capability, with catalog enumeration handled via a resource. There are no obvious missing operations for the server's stated purpose.
Maintenance
ActivityActive
ResponsivenessResponsive
Related MCP Connectors
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that connects any AI to your Obsidian vault. Save articles from your phone, search across notes, build a compounding knowledge base. 15 tools, three transport modes (stdio, HTTP, cloud), zero-install Google Drive OAuth onboarding.1513 npmMIT
- AlicenseAqualityDmaintenanceSemantic search over 4.6 million text chunks from 20,000+ classical philosophy and humanities works (pre-1928). Covers Aristotle, Plato, Kant, Hegel, Nietzsche and hundreds more. Multilingual: English, German, Latin, French, Italian, Greek, Russian.32MIT
- AlicenseAqualityAmaintenanceProvides access to 61 public digital libraries through a single unified interface, enabling users to search and retrieve information from academic papers, books, legal records, and more using natural language.1128 npm2MIT