Obsidian MCP (模型上下文协议) 服务器

英文 | 中文

该项目实现了一个模型上下文协议（MCP）服务器，用于连接AI模型与Obsidian知识库。通过此服务器，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框架提供战略洞察
• 🔗 自动回链生成: 新功能 智能检测并转换笔记名称为维基链接
• ⚡ 精确编辑: 高级PATCH操作，支持标题和块级定位
• 🚀 双重API策略: Obsidian REST API结合文件系统回退以确保最大可靠性
• 🎯 上下文优化: 智能内容总结，用于LLM上下文长度管理
• 📊 批量处理: 具有进度跟踪的高效批量操作

支持工具

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

📋 核心操作

• list_notes: 列出Obsidian保险库中的笔记，可选文件夹过滤
  • 新功能 recursive 参数：控制是否递归列出子目录中的文件（默认：true）
  • 使用 recursive: false 仅列出指定文件夹中的文件，不包括子目录
• read_note: 读取Obsidian保险库中特定笔记的内容
• read_multiple_notes: 同时读取多个笔记的内容，用于批量处理
• create_note: 在Obsidian保险库中创建带有完整内容的新笔记
• delete_note: 从Obsidian保险库中删除笔记
• search_vault: 跨所有文件类型进行高级搜索，匹配文件名和内容
• move_note: 移动或重命名笔记到新位置（支持所有文件类型，包括PDF）
• manage_folder: 完整的文件夹CRUD操作（创建/重命名/移动/删除）

🚀 高级功能

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

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

• auto_backlink_vault: 🔗 自动回链生成

  • 智能扫描整个保险库中的笔记名称提及
  • 将文本引用转换为维基链接格式（[[笔记名称]]）
  • 智能模式匹配，防止误报
  • 可配置的干运行模式和批量处理

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

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

先决条件

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

安装选项

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

方法	目标用户	优点	缺点
🎯 一键安装（DXT）	一般用户	最简单，图形界面配置	需要启用DXT的客户端
📦 远程安装（NPM）	Node.js用户	自动更新，无需安装	需要网络连接
🔧 本地部署	高级用户	离线使用，完全控制	需要手动更新

---

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

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

步骤1：下载DXT文件

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

步骤2：安装和配置

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

• Vault Path: 您的Obsidian保险库路径（例如，/Users/username/Documents/MyVault）
• API Token: Obsidian本地REST API插件令牌
• API Port: API端口号（默认：27123）

---

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

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

只需将以下配置添加到您的MCP客户端配置文件中：

使用npx（推荐，无需预先安装）：

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": [
        "@huangyihe/obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        ̶"O̶B̶S̶I̶D̶I̶A̶N̶_̶A̶P̶I̶_̶T̶O̶K̶E̶N̶":̶ ̶"̶y̶o̶u̶r̶_̶a̶p̶i̶_̶t̶o̶k̶e̶n̶"̶,
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

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

---

方法3：本地部署

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

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

步骤1：全局安装

npm install -g @huangyihe/obsidian-mcp

步骤2：MCP客户端配置

{
  "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：源码部署

步骤1：克隆仓库

git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp

步骤2：安装依赖

npm install

步骤3：构建项目

npm run build

步骤4：配置环境变量

cp .env.example .env
# 编辑.env文件以配置您的设置

步骤5：启动服务器

npm start

选项C：Docker部署

使用Docker Compose（推荐）

# 配置环境变量
cp .env.example .env
# 编辑.env文件

# 启动服务
docker-compose up -d

使用Docker命令

# 构建镜像
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保险库路径
• OBSIDIAN_API_TOKEN: Obsidian本地REST API插件的API令牌
• OBSIDIAN_API_PORT: Obsidian本地REST API的API端口（默认：27123）

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

获取API令牌

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

测试

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

node test-mcp.js

开发

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

许可证

MIT

贡献

欢迎提交拉取请求和问题！

相关项目

• 模型上下文协议
• Obsidian本地REST API