Obsidian 的 MCP 工具

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

Obsidian 的 MCP 工具使 AI 应用程序（如 Claude Desktop）能够通过模型上下文协议 (MCP) 安全地访问和使用您的 Obsidian vault。 MCP 是一种开放协议，它标准化了 AI 应用程序如何与外部数据源和工具交互，同时保持安全性和用户控制。[^2]

此插件包含两个部分：

1. 一个 Obsidian 插件，为您的 vault 添加 MCP 功能
2. 一个本地 MCP 服务器，用于处理与 AI 应用程序的通信

当您安装此插件时，它将帮助您设置这两个组件。 MCP 服务器充当您的 vault 和 AI 应用程序（如 Claude Desktop）之间的安全桥梁。 这意味着 AI 助手可以读取您的笔记、执行模板和执行语义搜索 - 但只有在您允许的情况下，并且只能通过服务器的安全 API。 服务器永远不会授予 AI 应用程序直接访问您的 vault 文件的权限。[^3]

隐私说明：默认情况下，将 Claude Desktop 与此插件一起使用时，您与 Claude 的对话不会用于训练 Anthropic 的模型。[^1]

功能

当连接到 MCP 客户端（如 Claude Desktop）时，此插件启用：

• Vault 访问：允许 AI 助手读取和引用您的笔记，同时保持您的 vault 的安全性[^4]
• 语义搜索：AI 助手可以根据含义和上下文搜索您的 vault，而不仅仅是关键字[^5]
• 模板集成：通过 AI 交互执行 Obsidian 模板，具有动态参数和内容生成[^6]

所有功能都需要 MCP 兼容的客户端（如 Claude Desktop），因为此插件提供服务器组件以启用这些集成。 该插件不会直接修改 Obsidian 的功能 - 而是创建一个安全桥梁，允许 AI 应用程序以强大的方式使用您的 vault。

先决条件

必需

• Obsidian v1.7.7 或更高版本
• 已安装并配置 Claude Desktop
• 已安装并配置 Local REST API 插件，并具有 API 密钥

推荐

• Templater 插件，用于增强模板功能
• Smart Connections 插件，用于语义搜索功能

安装

[!Important] 此插件需要一个安全的服务器组件，该组件在您的计算机本地运行。 该服务器以签名可执行文件的形式分发，其完整源代码可在 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. 使用您的 Local REST API 插件的 API 密钥
3. 配置 Claude Desktop 以使用 MCP 服务器
4. 设置适当的路径和权限

虽然配置过程是自动化的，但它需要您明确许可才能安装服务器二进制文件并修改 Claude Desktop 配置。 除了此初始设置步骤之外，无需其他手动配置。

故障排除

如果您遇到问题：

1. 检查插件设置以验证：
   • 已安装所有必需的插件
   • 服务器已正确安装
   • Claude Desktop 已配置
2. 查看日志：
   • 打开插件设置
   • 单击“资源”下的“打开日志”
   • 查找任何错误消息或警告
3. 常见问题：
   • 服务器无法启动：确保 Claude Desktop 正在运行
   • 连接错误：验证 Local 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 <binary path or URL>
   

验证将显示：

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

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

报告安全问题

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

开发

此项目使用具有基于功能的架构的 monorepo 结构。 有关详细的项目架构文档，请参阅 .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. Fork 存储库
2. 创建一个功能分支
3. 进行更改
4. 运行测试：

   bun test
   

5. 提交 pull request

有关详细的指南，请参阅 CONTRIBUTING.md。

支持

• 打开一个 issue 以报告错误和提出功能请求
• 开始讨论 以提出问题和获得一般帮助

更新日志

有关每个版本中的更改列表，请参阅 CHANGELOG.md。

许可证

MIT 许可证

脚注

[^1]: 有关 Claude 数据隐私和安全的信息，请参阅 Claude AI 的数据使用政策 [^2]: 有关模型上下文协议的更多信息，请参阅 MCP 简介 [^3]: 有关可用 MCP 客户端的列表，请参阅 MCP 示例客户端 [^4]: 需要 Obsidian 插件 Local REST API [^5]: 需要 Obsidian 插件 Smart Connections [^6]: 需要 Obsidian 插件 Templater