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
• 社区: https://t.zsxq.com/19IaNz5wK

功能

• 与Obsidian知识库无缝集成
• 支持读取、创建、更新和删除笔记
• 支持创建、重命名、移动和删除文件夹
• 全文搜索功能
• 符合模型上下文协议规范

支持的工具

MCP服务器提供以下工具：

• list_notes：列出Obsidian库中的所有笔记
• read_note：读取Obsidian库中的笔记内容
• read_multiple_notes：同时读取多个笔记的内容
• create_note：在Obsidian库中创建新笔记
• update_note：通过目标文本替换更新现有笔记中的内容
• search_vault：在Obsidian库中搜索内容
• delete_note：从Obsidian库中删除笔记
• move_note：将笔记移动或重命名到Obsidian库中的新位置
• manage_folder：在Obsidian库中创建、重命名、移动或删除文件夹
• auto_backlink_vault：🔗 自动反向链接 - 扫描整个库并智能检测笔记名称，自动将其转换为wikilink格式（[[笔记名称]]）

先决条件

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

安装选项

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

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

适用于： 希望获得最简单安装体验的普通用户

步骤1：下载DXT文件

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

步骤2：安装和配置

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

• 库路径：您的Obsidian库路径（例如，/Users/username/Documents/MyVault）
• API令牌：Obsidian Local REST API插件令牌
• API端口：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
# 编辑.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 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 Requests和Issues！

相关项目

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