Obsidian MCP

Obsidian MCP（模型上下文协议）服务

English | 中文

本项目实现了一个模型上下文协议（MCP）服务，用于连接 AI 模型与 Obsidian 知识库。通过此服务，AI 模型可以直接访问和操作 Obsidian 笔记，包括读取、创建、更新和删除笔记，以及管理文件夹结构。

由 huangyihe 创建

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

功能特性

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

支持的工具

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：🔗 自动生成反向链接

  • 智能扫描整个库，查找笔记名称的提及
  • 将文本引用转换为维基链接格式（[[note name]]）
  • 智能模式匹配，避免误报
  • 支持可配置的试运行模式和批量处理

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

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

前置条件

• Node.js（v16 或更高版本）
• Obsidian 桌面应用
• Obsidian Local 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 Local 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",
        "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
# Edit .env file with your configuration

步骤 5：启动服务

npm start

选项 C：Docker 部署

使用 Docker Compose（推荐）

# Configure environment variables
cp .env.example .env
# Edit .env file

# Start service
docker-compose up -d

使用 Docker 命令

# Build image
docker build -t obsidian-mcp .

# Run container
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 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）

测试

项目包含一个测试脚本，用于验证服务功能：

node test-mcp.js

开发

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

许可证

MIT

参与贡献

欢迎提交 Pull Request 和 Issues！

相关项目

• 模型上下文协议
• Obsidian Local REST API