Obsidian 的 MCP 工具

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

Obsidian 的 MCP 工具使 Claude Desktop 等 AI 应用程序能够通过模型上下文协议 (MCP) 安全地访问和使用您的 Obsidian 数据存储库。MCP 是一种开放协议，它规范了 AI 应用程序与外部数据源和工具交互的方式，同时确保安全性和用户控制权。[^2]

该插件由两部分组成：

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

安装此插件后，它将帮助您设置这两个组件。MCP 服务器充当您的 Vault 和 Claude Desktop 等 AI 应用程序之间的安全桥梁。这意味着 AI 助手可以读取您的笔记、执行模板并进行语义搜索 - 但前提是您允许，并且只能通过服务器的安全 API 进行访问。服务器绝不会允许 AI 应用程序直接访问您的 Vault 文件。[^3]

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

特征

当连接到 Claude Desktop 等 MCP 客户端时，此插件可以实现以下功能：

• 保险库访问：允许 AI 助手阅读和参考你的笔记，同时维护你的保险库安全 [^4]
• 语义搜索：人工智能助手可以根据含义和上下文（而不仅仅是关键词）搜索你的保险库[^5]
• 模板集成：通过 AI 交互执行 Obsidian 模板，具有动态参数和内容生成 [^6]

所有功能都需要一个兼容 MCP 的客户端，例如 Claude Desktop，因为此插件提供了支持这些集成的服务器组件。该插件不会直接修改 Obsidian 的功能，而是创建一个安全的桥梁，使 AI 应用程序能够以强大的方式与您的保险库协同工作。

先决条件

必需的

• Obsidian v1.7.7 或更高版本
• Claude Desktop安装和配置
• 已安装本地 REST API插件并使用 API 密钥进行配置

受到推崇的

• 用于增强模板功能的模板插件
• 用于语义搜索功能的智能连接插件

安装

重要提示：此插件需要一个在您的计算机上本地运行的安全服务器组件。该服务器以已签名的可执行文件形式分发，其完整源代码位于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 <binary path or URL>

验证将显示：

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

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

报告安全问题

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

发展

本项目采用基于特性的单体仓库架构。详细的项目架构文档，请参阅.clinerules 。

使用 Cline

本项目中的部分代码是使用 AI 编码代理Cline实现的。Cline 使用cline_docs/和.clinerules文件来理解项目架构和模式，以便实现新功能。

工作区

该项目采用Bun工作区结构：

建筑

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. 提交拉取请求

请参阅CONTRIBUTING.md了解详细指南。

支持

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

变更日志

请参阅CHANGELOG.md了解每个版本的更改列表。

执照

MIT 许可证

脚注

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