知识库AI集成服务

黑曜石MCP（模型上下文协议）服务器

英语| 中文

该项目实现了一个模型上下文协议（MCP）服务器，用于将AI模型与黑曜石知识库连接起来。通过该服务器，人工智能模型可以直接访问和操作黑曜石笔记，包括阅读、创建、更新和删除笔记，以及管理文件夹结构。

由黄一河创建

• Prompt House：https://prompthouse.app/
• 油管https://www.youtube.com/@华亿河777
• 推特：https://x.com/huangyihe
• 社区：https://t.zsxq.com/19IaNz5wK

特性

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

支持的工具

MCP服务器提供以下综合工具：

📋 核心业务

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

🚀 高级功能

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

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

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

  • 智能扫描整个保险库，查找钞票名称
  • 将文本引用转换为wikilink格式([[note name]])
  • 智能模式匹配与误报预防
  • 可配置的干运行模式和批处理

• notes_insight: 🧠 基于人工智能的战略分析 ⭐ 新

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

先决条件

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

安装选项

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

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

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

第一步：下载DXT文件

下载预构建的扩展包： 黑曜石-mcp.dxt

步骤2：安装和配置

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

• 保险库路径：您的黑曜石金库路径（例如。， /Users/username/Documents/MyVault)
• API代币：黑名单本地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
# 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_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 目录

许可证

麻省理工学院

贡献

欢迎提交请求和问题！

相关项目

• 模型上下文协议
• 黑名单本地REST API