Obsidian 的 MCP 工具

功能 | 安装 | 配置 | 故障排除 | 安全 | 开发 | 支持

🔄 寻找项目维护者

本项目正在积极寻找专职维护者来接手开发和社区管理。项目将继续保留在当前的 GitHub 账户下以符合 Obsidian 插件商店的要求，并添加新的维护者作为协作者。

感兴趣？ 加入我们的 Discord 社区 或查看我们的 维护者要求。

时间线：申请开放至 2025年9月15日。选择日期为 2025年9月30日。

MCP 工具为 Obsidian 提供了通过模型上下文协议（MCP）让 AI 应用程序如 Claude Desktop 安全访问和操作你的 Obsidian 保险库的能力。MCP 是一个开放协议，标准化了 AI 应用程序如何与外部数据源和工具交互，同时保持安全性和用户控制。¹

该插件由两部分组成：

1. 一个为你的保险库增加 MCP 功能的 Obsidian 插件
2. 一个处理与 AI 应用程序通信的本地 MCP 服务器

当你安装此插件时，它会帮助你设置这两个组件。MCP 服务器充当你的保险库和 AI 应用程序之间的安全桥梁。这意味着 AI 助手可以读取你的笔记、执行模板并进行语义搜索——但只有在你允许的情况下，并且仅通过服务器的安全 API 进行。服务器不会给 AI 应用程序直接访问你的保险库文件的权限。²

隐私说明：使用 Claude Desktop 和此插件时，默认情况下，你与 Claude 的对话不会用于训练 Anthropic 的模型。³

功能

当连接到像 Claude Desktop 这样的 MCP 客户端时，此插件启用：

• 保险库访问：允许 AI 助手读取和引用你的笔记，同时保持保险库的安全性⁴
• 语义搜索：AI 助手可以根据意义和上下文搜索你的保险库，而不仅仅是关键词⁵
• 模板集成：通过 AI 交互执行 Obsidian 模板，具有动态参数和内容生成⁶

所有功能都需要像 Claude Desktop 这样的 MCP 兼容客户端，因为此插件提供了使这些集成成为可能的服务器组件。插件不会直接修改 Obsidian 的功能——相反，它创建了一个安全桥梁，允许 AI 应用程序以强大的方式与你的保险库互动。

预备条件

必需

• Obsidian v1.7.7 或更高版本
• 已安装并配置好的 Claude Desktop
• 已安装并配置好带有 API 密钥的 本地 REST API 插件

推荐

• Templater 插件以增强模板功能
• Smart Connections 插件以实现语义搜索能力

安装

[!重要] 此插件需要一个运行在你计算机上的本地安全服务器组件。服务器以签名可执行文件的形式分发，其完整源代码可以在 packages/mcp-server/ 中找到。有关我们安全措施和代码签名过程的详细信息，请参阅 安全 部分。

1. 从 Obsidian 的社区插件中安装插件
2. 在 Obsidian 设置中启用插件
3. 打开插件设置
4. 点击“安装服务器”下载并配置 MCP 服务器

点击安装按钮将：

• 下载适合你平台的 MCP 服务器二进制文件
• 配置 Claude Desktop 使用服务器
• 设置必要的权限和路径

安装位置

• 服务器二进制文件：{vault}/.obsidian/plugins/obsidian-mcp-tools/bin/
• 日志文件：
  • macOS：~/Library/Logs/obsidian-mcp-tools
  • Windows：%APPDATA%\obsidian-mcp-tools\logs
  • Linux：~/.local/share/obsidian-mcp-tools/logs

配置

点击插件设置中的“安装服务器”按钮后，插件将自动：

1. 下载适合的 MCP 服务器二进制文件
2. 使用你的本地 REST API 插件的 API 密钥
3. 配置 Claude Desktop 使用 MCP 服务器
4. 设置适当的路径和权限

虽然配置过程是自动化的，但它需要你明确许可安装服务器二进制文件并修改 Claude Desktop 的配置。除了这个初始设置步骤外，不需要额外的手动配置。

故障排除

如果你遇到问题：

1. 检查插件设置以验证：
   • 所有必需的插件已安装
   • 服务器已正确安装
   • Claude Desktop 已配置
2. 查看日志：
   • 打开插件设置
   • 在资源下点击“打开日志”
   • 查找任何错误消息或警告
3. 常见问题：
   • 服务器无法启动：确保 Claude Desktop 正在运行
   • 连接错误：验证本地 REST API 插件是否已配置
   • 权限错误：尝试重新安装服务器

安全

二进制分发

• 所有发布都是使用 GitHub Actions 构建的，具有可重复构建
• 二进制文件使用 SLSA 证明签名
• 发布工作流程在存储库中完全可审计

运行时安全

• MCP 服务器以最小的必要权限运行
• 所有通信都是加密的
• API 密钥使用平台特定的凭证存储安全存储

二进制验证

MCP 服务器二进制文件发布时附带 SLSA 证明签名，提供二进制文件构建地点和方式的加密证明。这有助于确保你下载的二进制文件的完整性和来源。

要使用 GitHub CLI 验证二进制文件：

1. 安装 GitHub CLI：

   # macOS (Homebrew)
   brew install gh
   
   # Windows (Scoop)
   scoop install gh
   
   # Linux
   sudo apt install gh  # Debian/Ubuntu
   

2. 验证二进制文件：

   gh attestation verify --owner jacksteamdev <二进制文件路径或URL>
   

验证将显示：

• 二进制文件的 SHA256 哈希值
• 确认它是由此存储库的 GitHub Actions 工作流构建的
• 创建它的具体工作流文件和版本标签
• 符合 SLSA 三级构建要求

这种验证确保二进制文件没有被篡改，并且是从此存储库的源代码直接构建的。

报告安全漏洞

请通过我们的 安全政策 报告安全漏洞。 不要在公共问题中报告安全漏洞。

开发

该项目采用单仓库结构和基于特性的架构。有关详细的项目架构文档，请参阅 .clinerules。

使用 Cline

该项目中的一些代码是使用 AI 编码代理 Cline 实现的。Cline 使用 cline_docs/ 和 .clinerules 文件来理解项目架构和模式，以便在实现新特性时使用。

工作空间

该项目使用 Bun 工作空间结构：

packages/
├── mcp-server/        # 服务器实现
├── obsidian-plugin/   # Obsidian 插件
└── shared/           # 共享实用工具和类型

构建

1. 安装依赖项：

   bun install
   

2. 构建所有包：

   bun run build
   

3. 开发：

   bun run dev
   

要求

• bun v1.1.42 或更高版本
• TypeScript 5.0+

贡献

在贡献之前，请阅读我们的 贡献指南，包括我们的社区标准和行为期望。

1. 分叉存储库
2. 创建一个功能分支
3. 进行更改
4. 运行测试：

   bun test
   

5. 提交拉取请求

我们欢迎真诚的贡献，但坚持严格的社区标准。在所有互动中保持尊重和建设性。

支持

• 💬 加入我们的 Discord 以获取问题解答、讨论和社区支持
• 打开一个问题 以报告错误或提出功能请求

在发帖前，请阅读我们的 贡献指南。 我们维持高标准的社区规范，并对有毒行为零容忍。

变更日志

详见 GitHub 发布 以获取详细的变更日志信息。

许可证

MIT 许可证

脚注

Footnotes

1. 有关模型上下文协议的更多信息，请参阅 MCP 介绍 ↩

2. 有关可用的 MCP 客户端列表，请参阅 MCP 示例客户端 ↩

3. 关于 Claude 数据隐私和安全的信息，请参阅 Claude AI 的数据使用政策 ↩

4. 需要 Obsidian 插件 Local REST API ↩

5. 需要 Obsidian 插件 Smart Connections ↩

6. 需要 Obsidian 插件 Templater ↩