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
99 npm
30
MIT
obsidian-tc
Governed, agent-ready MCP server for Obsidian vaults — lets you discover and invoke 163 capabilities across access, retrieval, memory, and administration through a 3-tool facade.
Discover and call tools safely —
find_capabilitysearches by natural language,describe_capabilityreturns schemas and safety hints, andcall_capabilityinvokes any tool through the same auth/ACL/HITL/audit pipeline.Read and search vault content — full-text, semantic/vector, graph, regex, DQL, Omnisearch, properties, tags, backlinks, attachments, canvas/Excalidraw/Base, periodic notes, snapshots, and more.
Write and manage notes — create, append, patch, write, move, copy, delete, bulk operations, frontmatter/properties, tables, tags, tasks, bookmarks, kanban, workspaces, templates, git staging/commits, and restore.
Use in-vault memory — episodes, entity graph, observations, goals, retrieval feedback, decay/forgetting, session tracking, and knowledge search.
Administer and govern — add/reload/index vaults, inspect ACLs and visibility, view server config/metrics, refresh plugin capabilities, and reset caches.
Safety built in — auth, folder ACLs, read-only kill switch, human-in-the-loop confirmation on destructive ops, and audit logging across every call.
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.
163 tools across 31 domains (all visible by default; 97 with opt-in profile: "core"), via a
3-tool facade. 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 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.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 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/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 | 163 (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 · 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 plugin is not the server — governance/retrieval run in the obsidian-tc process, 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.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:
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.
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.
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.
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.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
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.157 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.31MIT
- 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.41130 npm2MIT