Obsidian MCP Server

obsidian-mcp-server 是一个实现了 Model Context Protocol (MCP) 的服务器，它提供强大的工具API，使得可以轻松地在AI代理或外部应用程序中探索和管理本地 Obsidian 保险库中的文档。

该服务器旨在通过使用 Obsidian 保险库扩展成可被AI利用的知识库，自动化诸如文档搜索、摘要生成和整理等附加任务，从而构建一个让用户能够专注于核心“写作活动”的环境。

核心架构

本服务器围绕 VaultManager 和 Indexer 构建，确保在大规模保险库中也能保持高性能和内存效率。

• 基于 Indexer 的搜索：服务器启动时创建轻量级倒排索引，使关键词搜索几乎能立即返回结果（O(1)）。由于不将整个文件内容保留在内存中，因此最大限度地减少了内存使用。
• VaultManager：高效管理保险库内的所有文档，并与文件系统交互以处理文档的创建、修改和删除。

主要功能

• 高级文档探索：通过 vault 工具提供多种探索功能，包括关键词搜索、查询全部列表、读取特定文档以及统计分析等。
• 基于AI的属性生成：generate_property 工具分析文档正文，自动生成适当的 frontmatter 属性，如 title、tags 和 summary。
• 安全属性更新：使用 write_property 工具将生成的属性与现有 frontmatter 合并，并安全地记录到文件中。
• 自动整理附件：organize_attachments 工具自动检测与文档关联的所有附件（例如图像），并将它们移动到与文档标题匹配的文件夹中，并更新链接。
• 集成工作流：通过 create_document_with_properties 等工具，实现从文档分析到属性生成再到文件更新的全过程，只需单个命令即可执行。
• 可靠性和测试：使用 vitest 进行端到端测试，并通过基于 GitHub Actions 的 CI/CD 管道验证服务器的稳定性及各工具API的响应模式。

工具API

obsidian-mcp-server 提供以下可通过 MCP 客户端调用的工具：

vault

这是用于探索和分析保险库内文档的核心工具。通过 action 参数可以执行各种功能。

• list_all：返回保险库内所有文档的列表及其元数据。
• search：根据关键词搜索文档标题、内容和标签。
• read：读取特定文件的内容，并返回 frontmatter 和正文。
• stats：提供保险库内所有文档的统计数据（如单词数、字符数等）。

generate_property

接收文档路径（filePath）作为输入，分析该文档的内容，并返回由AI推荐的 frontmatter 属性。

write_property

接收文件路径（filePath）和 JSON 格式的属性（properties）作为输入，更新该文件的 frontmatter。

create_document_with_properties

这是一个集成工具，一次性处理文档分析、属性生成和文件更新的全过程。

organize_attachments

通过关键词查找文档，并将与该文档关联的所有附件移动到 images/{文档标题} 文件夹中，并自动更新文档内的链接。

开始使用

1. 复制存储库并安装依赖项：

   git clone https://github.com/sunub/obsidian-m-mp-server.git
   cd obsidian-mcp-server
   npm install
   

2. 设置环境变量： 在项目根目录下创建 .env 文件，并指定 Obsidian 保险库的绝对路径。

   VAULT_DIR_PATH=/path/to/your/obsidian/vault
   

3. 构建项目：

   npm run build
   

4. 运行服务器：

   node build/index.js
   

   现在可以通过 MCP 客户端连接到服务器并使用这些工具了。

开发

执行测试

可以使用 vitest 来运行端到端测试。

npm test

CI/CD

此项目使用 GitHub Actions 构建了 CI/CD 管道。当向 main 分支推送代码或发起拉取请求时，会自动执行构建和测试。