Obsidian Turbocharged

obsidian-tc

Obsidian Turbocharged —— 通过 MCP 提供受治理、适用于 Agent 的知识库访问。

项目简介

obsidian-tc 是一款面向 Obsidian 知识库、供人类和 Agent 使用的受治理、适用于 Agent 的模型上下文协议服务。它不直接访问多年笔记所在的文件系统，而是让每次工具调用都经过同一条处理流程——身份验证、文件夹 ACL、只读紧急开关、破坏性操作的 HITL 确认，以及审计日志。它还添加了融合检索（全文、向量、图谱）和记忆层——情节、衰减、遗忘——并在同一 ACL 的管控下存储于你的知识库中。 涵盖所有领域的完整工具集（默认全部可见；也可通过 profile: "core" 选择较小的工具集），通过由 3 个工具组成的发现门面以及标准的 search/fetch 工具对提供，详见工具目录。项目介绍：docs/WHY.md。

60 秒快速开始

无需安装：

npx obsidian-tc /path/to/vault

所有笔记工具和词法搜索都可以立即使用。语义搜索默认使用捆绑的嵌入器——哪些安装方式可以使用它，请参阅不适用场景。

如需使用多个知识库、身份验证或 ACL，请使用配置文件：

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

默认的 local 嵌入器需选择安装，因此 npm install -g obsidian-tc 不会将其一并安装。如需使用，请安装相同版本：npm install -g @the-40-thieves/obsidian-tc-embedder-local@<same version>（项目安装时去掉 -g），或让 obsidian-tc setup 提供安装选项。Ollama 和托管式嵌入服务提供商不需要本地嵌入器；若未配置任何嵌入器，语义搜索会关闭，其他功能仍可正常使用。

也提供 Docker 镜像、.mcpb 包和独立二进制文件。更多信息： docs/QUICKSTART.md。

不适用场景

坦诚说明——与大多数产品相比，这款产品较为复杂：

• 希望占用资源尽可能少、只读访问，或完全不使用 MCP。 如果只有一位可信的人使用一个知识库，只需要一个只读封装，或者 Obsidian URI/Local REST API 插件就能满足需求——请参阅完整对比。
• 希望零配置，且仅使用源码检出。 知识库从磁盘读取；语义搜索默认使用捆绑的离线嵌入器；npm/Docker 在发布前需要显式指定提供商——请参阅嵌入。
• 零配置意味着放弃身份验证和 ACL。 obsidian-tc /path/to/vault 启动时默认关闭身份验证，也没有文件夹 ACL——这仅适用于本地使用；治理功能需要主动启用。详情请见：SECURITY.md。
• AGPL-3.0 的网络 copyleft 条款。 该许可证并非宽松型；可能提供商业许可证——请参阅许可证。
• 由单一维护者维护的项目。
• 所有内容都必须在 Obsidian 内，或需要独立于知识库的记忆。 请参阅上文的对比。

从其他 MCP 服务迁移：docs/CUTOVER.md。

对比

大多数 Obsidian MCP 项目是知识库访问服务、检索引擎或记忆引擎，极少同时具备多个功能。据我们所知，obsidian-tc 是唯一一个三者兼备的项目，记忆存储在知识库中，并遵循与所有其他写入操作相同的 ACL。完整的 9 个项目对比表及“其他项目的优势”。

	工具	分组	用途
obsidian-tc	完整功能（3 工具门面）	三者兼备	受控访问 + 检索 + 知识库内记忆
obsidian-local-rest-api	18	访问	Obsidian 自带的 MCP 服务；单个 bearer 密钥，无 ACL
basic-memory	~35	记忆	存储在独立、可移植的 Markdown 知识库中的实体/关系

---

更多

目录

TC Bridge · 状态 · 架构 · 接口 · Claude Code / Cursor / VS Code · 文档 · 商标 · 许可证 · 贡献

TC Bridge：配套 Obsidian 插件

如果你是从 Obsidian 的插件浏览器来到这里的：TC Bridge 插件条目会指向此处，因为该插件位于此代码库中，但它只是一个小型可选桥接插件，并非上文所述的服务。它扩展了 Local REST API，为 Obsidian 专属功能（Templater、Dataview、Tasks、Excalidraw、Git、Remotely Save）提供端点。所有文件系统级功能都无需此插件即可使用。

• 请先安装 Local REST API；TC Bridge 会复用其 bearer-token 身份验证，且仅支持桌面端。服务需单独安装（60 秒即可启动）；要访问这些桥接功能，需在知识库配置中设置 restApiUrl/restApiKey （第 6 步）。该密钥相当于知识库根密码——请先阅读信任边界。
• 原名为“Obsidian Turbocharged”。 设置会在首次加载时迁移——详情请见 packages/plugin/README.md。

状态

已发布 — v1.33.1，已作为带来源证明签名的软件包发布到 npm，容器镜像托管于 GHCR。 里程碑：路线图；发行版本： CHANGELOG.md。

检索变更经过测量，而非仅凭断言：每项排名变更都必须通过统计学发布规则，在私有黄金测试集上进行验证。本 README 曾列出的主要数据因无法复现，已于 2026-08-07 撤下——完整说明及此后在公开语料上的测试结果见： docs/EVALUATION.md。

架构

多语言单体仓库：

包	语言	用途
packages/server	TypeScript (Bun)	MCP 层、身份验证、路由、工具、插件桥接
packages/plugin	TypeScript	扩展 Local REST API 的配套 Obsidian 插件
packages/shared	TypeScript	共享的 Zod 模式和类型
packages/native	Rust (napi-rs)	可选加速，纯 JS 后备方案

分发管道和包布局详情：ARCHITECTURE.md。

每项功能都是受治理的工具，并声明访问范围。读取工具（read_note、 search_vault、get_backlinks 等）绝不会修改知识库。写入工具涵盖整篇笔记和 局部编辑：write_note、append_note、patch_note（以标题和块为锚点的编辑）、 update_frontmatter、标签和链接维护。独立的范围类别用于控制删除和移动 （delete_note、move_note）、批量操作（bulk_set_property）、执行（execute_command） 和管理（add_vault、reload_vault）。按访问范围分组、由工具注册表生成的完整且始终最新的列表，见 工具目录。

接口：五个工具，覆盖所有受治理的功能

默认情况下，服务仅公布五个工具，而不是多达 164 个工具的冗长列表：三个元工具 find_capability、describe_capability、call_capability（按名称调用，使用与直接调用相同的管道）， 以及 ChatGPT 深度研究所需的标准 search 和 fetch 工具。toolFacade.mode 可选择 triad（默认）、domain 或 flat（也提供已被取代的 auto） ——仅改变边界，不会绕过任何门控。各客户端的建议：MCP 客户端。

在 Claude Code、Cursor、VS Code 中安装

Claude Code 插件（启动 npx -y obsidian-tc，启用时会询问配置文件路径）：

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

Grok Build 和 Muse Code（1.4.0+）使用同一市场；详情见 安装。

在 VS Code Insiders 中安装

也可以手动配置——Cursor（mcpServers）/ VS Code（servers）使用相同对象： {"command": "npx", "args": ["-y", "obsidian-tc"], "env": {"OBSIDIAN_TC_CONFIG": "/ABS/config.json"}}。 .mcpb 捆绑包（bun run bundle）也可安装到 Claude Desktop / 其他 MCPB 宿主中。 有关 claude.ai 和 ChatGPT（远程 HTTP），请参阅分发。

文档

• docs/QUICKSTART.md — 从安装到首次受治理写入，约 5 分钟
• docs/WHY.md / SECURITY.md — 威胁模型、治理
• docs/CUTOVER.md — 从其他 Obsidian MCP 服务迁移
• docs/EVALUATION.md — 如何衡量检索变更
• ARCHITECTURE.md — 分发管线、软件包布局
• 文档网站：https://obsidian-tc.the40thieves.io（Getting Started 下有完整对比）

商标

obsidian-tc 是独立的社区项目，与 Obsidian 或其制作方 Dynalist Inc. 无关，也未获其认可。“Obsidian”是 Dynalist Inc. 的商标，此处仅作指称之用。 官方应用：obsidian.md。

许可证

AGPL-3.0-only。请参阅 LICENSE 和许可常见问题；也可能存在商业例外——请发起讨论。 贡献须遵循 DCO；请在 CONTRIBUTING.md 中完成签署。

贡献

请参阅 CONTRIBUTING.md / 行为准则。 安全：SECURITY.md。