黑曜石-MCP服务器

作者：Xe1380 星标更新：2025-11-16

安装使用来源：spider==github.com

项目介绍

MCP Server 插件

一个插件，使你的保险库可以通过模型上下文协议（MCP）通过HTTP访问。这允许AI助手和其他MCP客户端以编程方式与你的保险库进行交互。

版本: 1.0.0 | 已测试版本: Obsidian v1.9.14 | 许可证: MIT

⚠️ 安全提示

该插件运行一个HTTP服务器，向MCP客户端（如AI助手）公开你的保险库内容。虽然服务器仅绑定到本地主机并强制身份验证，但请注意，任何拥有你的API密钥的客户端都可以读取、创建、修改和删除保险库中的文件。仅将你的API密钥分享给可信赖的应用程序。

功能

HTTP MCP服务器: 运行一个实现MCP协议的HTTP服务器
保险库操作: 提供用于读取、创建、更新和删除笔记的工具
搜索功能: 按内容或文件名搜索笔记
安全性: 仅绑定到本地主机，强制身份验证，加密存储API密钥
简单配置: 简单的设置UI，包括服务器状态和控制

可用的MCP工具

笔记操作

read_note - 读取笔记内容，可选解析前置元数据
create_note - 创建新的笔记，并处理冲突策略
update_note - 更新现有笔记（替换全部内容）
delete_note - 删除笔记（软删除至.trash或永久删除）
update_frontmatter - 更新前置元数据字段而不修改笔记内容
update_sections - 根据行范围更新笔记的特定部分
rename_file - 重命名或移动文件，并自动更新维基链接
read_excalidraw - 读取Excalidraw绘图文件并提取元数据（目前仅限于未压缩格式；计划支持压缩格式）

保险库操作

search - 使用高级过滤器、正则表达式支持和片段提取搜索保险库
search_waypoints - 在保险库中查找所有Waypoint插件标记
list - 列出文件和/或目录，带有高级过滤器和分页
stat - 获取文件或文件夹的详细元数据
exists - 检查特定路径下的文件或文件夹是否存在
get_vault_info - 获取保险库元数据（名称、路径、文件数量、总大小）

Waypoint集成

get_folder_waypoint - 从文件夹笔记中获取Waypoint块
is_folder_note - 检查笔记是否是文件夹笔记

链接管理

validate_wikilinks - 验证笔记中的所有维基链接，并报告未解决的链接
resolve_wikilink - 解析源笔记中的单个维基链接到其目标路径
backlinks - 获取指向笔记的所有反向链接，可选未链接提及

安装

从Obsidian社区插件

注意: 此插件正在等待社区插件目录的审批。一旦获得批准，它将可供一键安装。

当可用时：

打开Obsidian设置 → 社区插件
选择浏览并搜索"MCP Server"
点击安装
启用插件

从源码

前提条件: 系统上必须安装Node.js和npm。

将此仓库克隆到你的保险库插件文件夹中：

cd /path/to/vault/.obsidian/plugins
git clone https://github.com/Xe138/obsidian-mcp-server.git obsidian-mcp-server
cd obsidian-mcp-server

安装依赖项：
```
npm install
```
构建插件：
```
npm run build
```
在Obsidian设置 → 社区插件中启用插件

配置

打开Obsidian设置 → MCP Server
配置以下选项：
- 端口: HTTP服务器端口（默认：3000）
- 自动启动: 自动在Obsidian启动时启动服务器
- API密钥: 自动生成并加密的身份验证令牌（可在设置中重新生成）
点击“启动服务器”或使用侧边栏图标切换服务器

身份验证

当你首次安装插件时，会自动生成一个API密钥，并使用系统安全凭证存储（macOS钥匙串、Windows凭据管理器、Linux Secret Service）进行加密。

使用方法

启动服务器

通过侧边栏图标: 点击左侧边栏的服务器图标
通过命令面板: 运行"Start MCP Server"
自动启动: 在设置中启用以自动启动

连接MCP客户端

服务器在以下地址提供MCP端点：

http://127.0.0.1:3000/mcp

示例客户端配置（例如，用于Claude Desktop）：

{
  "mcpServers": {
    "obsidian": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

要获取你的API密钥:

打开Obsidian设置 → MCP Server
在身份验证部分找到API密钥字段
点击复制图标将你的API密钥复制到剪贴板
将示例中的YOUR_API_KEY替换为你实际的密钥

所有请求都必须包含Bearer令牌：

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

示例MCP请求

初始化连接

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

列出可用工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

读取笔记

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "read_note",
    "arguments": {
      "path": "folder/note.md"
    }
  }
}

创建笔记

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "path": "new-note.md",
      "content": "# 新笔记\n\n这是内容。"
    }
  }
}

搜索笔记

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "搜索词"
    }
  }
}

故障排除

服务器无法启动

端口已被占用:

另一个应用程序正在使用端口3000
在设置 → MCP Server → 端口中更改端口
常见替代端口：3001, 8080, 8000

权限被拒绝:

在Linux/macOS上，低于1024的端口需要root权限
使用大于1024的端口号（默认3000即可）

身份验证失败

无效的API密钥:

再次从设置 → MCP Server复制API密钥
确保你包含完整的密钥且没有额外空格
尝试使用“重新生成API密钥”按钮重新生成API密钥

401未经授权:

检查Authorization头是否正确格式化：Bearer YOUR_API_KEY
确认“Bearer”和密钥之间有一个空格

连接问题

无法连接到服务器:

确认服务器正在运行（检查侧边栏图标或设置中的状态）
确保你使用的是http://127.0.0.1:3000/mcp（某些系统上不是localhost）
检查是否有防火墙阻止了本地连接

CORS错误:

服务器仅接受来自localhost来源的请求
如果使用基于web的客户端，请确保它运行在localhost或127.0.0.1

一般问题

插件无法加载:

确保你在设置 → 社区插件中启用了插件
尝试禁用并重新启用插件
检查开发者控制台（Ctrl+Shift+I）中的错误消息

更改未生效:

重新加载Obsidian（Ctrl/Cmd + R）
如果是从源码构建，请确保npm run build成功完成

安全考虑

插件实现了多层安全措施：

网络绑定: 服务器仅绑定到127.0.0.1（无外部访问）
主机头验证: 防止DNS重新绑定攻击
CORS策略: 固定的localhost-only策略允许基于web的客户端在localhost或127.0.0.1（任何端口）
强制身份验证: 所有请求都需要Bearer令牌
加密存储: 当可用时，使用系统钥匙串加密API密钥
仅限桌面: 由于HTTP服务器需求，此插件仅适用于桌面（不适用于移动设备）

开发

从源码构建

npm install
npm run dev    # 开发模式
npm run build  # 生产构建

修改main.ts（或创建新的.ts文件）。这些更改应自动编译成main.js。
重新加载Obsidian以加载插件的新版本。
在设置窗口中启用插件。
对于Obsidian API的更新，请在你的仓库文件夹下运行命令行中的npm update。

贡献

欢迎贡献！请参阅贡献指南，了解详细信息：

开发环境和工作流程
代码风格和架构指南
测试要求
拉取请求过程
发布程序

贡献者快速入门

分叉仓库
创建特性分支（git checkout -b feature/amazing-feature）
编写测试并进行更改
运行npm test和npm run build
提交更改
推送到分支（git push origin feature/amazing-feature）
打开拉取请求

报告问题

发现bug或有功能请求？请在GitHub上打开一个问题：

GitHub问题: https://github.com/Xe138/obsidian-mcp-server/issues

报告bug时，请包括：

Obsidian版本
插件版本
操作系统
复现问题的步骤
开发者控制台中的任何错误消息（Ctrl+Shift+I）

支持

如果你觉得这个插件有用，请考虑支持其开发：

GitHub赞助: https://github.com/sponsors/Xe138

买我一杯咖啡: https://buymeacoffee.com/xe138

许可证

本项目采用MIT许可证。请参阅仓库以获取完整的许可详情。