Obsidian MCP (Model Context Protocol) 服务器

English | 中文

该项目实现了用于连接AI模型与Obsidian知识库的Model Context Protocol (MCP) 服务器。通过这个服务器，AI模型可以直接访问和操作Obsidian笔记，包括读取、创建、更新和删除笔记，以及管理文件夹结构。

由huangyihe创建

• Prompt House: https://prompthouse.app/
• YouTube: https://www.youtube.com/@huanyihe777
• Twitter: https://x.com/huangyihe
• 社区: https://t.zsxq.com/19IaNz5wK

功能

• 🔗 无缝Obsidian集成: 通过MCP协议直接访问Obsidian知识库
• 📝 完整的笔记管理: 读取、创建、更新和删除笔记，并支持高级文本替换
• 📁 文件夹操作: 创建、重命名、移动和删除文件夹，支持完整的层级结构
• 🔍 智能搜索: 支持所有文件类型的全文搜索，并具有智能评分
• 🤖 AI驱动的分析: 新 使用TRILEMMA-PRINCIPLES框架的战略洞察
• 🔗 自动生成反向链接: 新 智能检测并将笔记名称转换为wikilinks
• ⚡ 精准编辑: 高级PATCH操作，支持标题和块级定位
• 🚀 双API策略: Obsidian REST API结合文件系统回退机制以实现最大可靠性
• 🎯 上下文优化: 智能内容摘要，用于LLM上下文长度管理
• 📊 批量处理: 高效的批量操作并跟踪进度

支持的工具

MCP服务器提供了以下全面的工具：

📋 核心操作

• list_notes: 列出Obsidian库中的所有笔记，可选文件夹过滤
• read_note: 读取Obsidian库中特定笔记的内容
• read_multiple_notes: 同时从多个笔记中读取内容，适用于批量处理
• create_note: 在Obsidian库中创建一个带有完整内容的新笔记
• delete_note: 从Obsidian库中删除一个笔记
• search_vault: 跨所有文件类型进行高级搜索，支持文件名和内容匹配
• move_note: 将笔记移动或重命名到新位置（支持所有文件类型，包括PDF）
• manage_folder: 完整的文件夹CRUD操作（创建/重命名/移动/删除）

🚀 高级功能

• update_note: 增强 使用文本替换或精准插入来更新内容

  • 传统的文本替换模式
  • 新 基于标题的插入（之前/之后/追加/前置）
  • 新 支持^block-id的基于块ID的插入
  • 新 与文件系统回退机制集成的PATCH API

• auto_backlink_vault: 🔗 自动生成反向链接

  • 智能扫描整个库中的笔记名称提及
  • 将文本引用转换为wikilink格式（[[note name]]）
  • 智能模式匹配，防止误报
  • 可配置的预览模式和批量处理

• notes_insight: 🧠 AI驱动的战略分析 ⭐ 新

  • 使用TRILEMMA-PRINCIPLES框架生成战略洞察
  • 自动基于主题发现笔记并进行相关性排名
  • AI驱动的内容摘要，用于上下文优化
  • 结构化分析：识别约束 → 挑战假设 → 突破解决方案
  • 可配置的分析深度和范围参数

先决条件

• Node.js (v16 或更高版本)
• Obsidian桌面应用程序
• Obsidian Local REST API插件（需要在Obsidian中安装）

安装选项

根据您的技术水平和使用需求选择最合适的安装方法：

方法1：一键安装（DXT 包）- ✅ 推荐

适用对象： 希望获得最简单安装体验的一般用户

第一步：下载 DXT 文件

下载预构建的扩展包：obsidian-mcp.dxt

第二步：安装和配置

双击下载的 .dxt 文件，系统将自动安装扩展。然后填写配置界面：

• Vault 路径：您的 Obsidian vault 路径（例如，/Users/username/Documents/MyVault）
• API 令牌：Obsidian Local REST API 插件令牌
• API 端口：API 端口号（默认：27123）

方法2：远程安装（NPM 包）

适用对象： 希望自动更新和版本管理的 Node.js 开发者

只需在您的 MCP 客户端配置文件中添加以下配置即可：

使用 npx（推荐，无需预先安装）：
json
{
"mcpServers": {
"obsidian-mcp": {
"command": "npx",
"args": [
"@huangyihe/obsidian-mcp"
],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}

注意：首次运行会自动下载包，后续运行使用缓存，确保您始终使用最新版本。

方法3：本地部署

适用对象： 需要自定义、高级控制或离线使用的用户

选项 A：全局安装（推荐）

第一步：全局安装
bash
npm install -g @huangyihe/obsidian-mcp

第二步：MCP 客户端配置
json
{
"mcpServers": {
"obsidian-mcp": {
"command": "obsidian-mcp",
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}

选项 B：源码部署

第一步：克隆仓库
bash
git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp

第二步：安装依赖
bash
npm install

第三步：构建项目
bash
npm run build

第四步：配置环境变量
bash
cp .env.example .env

编辑 .env 文件以进行配置

第五步：启动服务器
bash
npm start

选项 C：Docker 部署

使用 Docker Compose（推荐）

bash

配置环境变量

cp .env.example .env

编辑 .env 文件

启动服务

docker-compose up -d

使用 Docker 命令

bash

构建镜像

docker build -t obsidian-mcp .

运行容器

docker run -d
--name obsidian-mcp
--env-file .env
--network host
-v $(OBSIDIAN_VAULT_PATH):$(OBSIDIAN_VAULT_PATH)
obsidian-mcp

配置指南

环境变量

所有安装方法都需要以下配置：

• OBSIDIAN_VAULT_PATH：您的 Obsidian vault 路径
• OBSIDIAN_API_TOKEN：Obsidian Local REST API 插件的 API 令牌
• OBSIDIAN_API_PORT：Obsidian Local REST API 的 API 端口（默认：27123）

⚠️ 重要提示：对于远程 NPM 安装和全局安装，必须使用 OBSIDIAN_ 前缀作为环境变量。不带前缀的 VAULT_PATH 和 API_TOKEN 将无法正常工作。

获取 API 令牌

1. 在 Obsidian 中安装 "Local REST API" 插件
2. 在插件设置中生成 API 令牌
3. 记录端口号（默认为 27123）

测试

项目包含一个测试脚本来验证服务器功能：

bash
node test-mcp.js

开发

• 使用 npm run dev 以开发模式运行服务器
• 源代码位于 src 目录中

许可证

MIT

贡献

欢迎提交 Pull Requests 和 Issues！

相关项目

• Model Context Protocol- Obsidian 本地 REST API