AI导哈

MCP服务器插件

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

  • by Xe138
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Xe138/obsidian-mcp-server

使用说明

MCP服务器插件

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

版本： 1.0.0 | 测试方法： 黑曜石v1.9.14| 许可证： 麻省理工学院

⚠️ 安全通知

此插件运行一个HTTP服务器，将您的保险库内容暴露给MCP客户端（如AI助手）。当服务器为本地主机且具有强制身份验证时，请注意，任何具有API密钥的客户端都可以读取、创建、修改和删除vault中的文件。仅与受信任的应用程序共享API密钥。

特性

  • HTTP MCP服务器：运行实现MCP协议的HTTP服务器
  • 保险库操作：显示用于阅读、创建、更新和删除笔记的工具
  • 搜索功能：按内容或文件名搜索笔记
  • 安全：本地主机绑定、强制身份验证、加密的API密钥存储
  • 易于配置：具有服务器状态和控件的简单设置UI

可用的MCP工具

注释操作

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

保险库操作

  • search -具有高级过滤、正则表达式支持和代码段提取功能的搜索库
  • search_waypoints -在vault中查找所有Waypoint插件标记
  • list -列出具有高级过滤和分页功能的文件和/或目录
  • stat -获取文件或文件夹的详细元数据
  • exists -检查特定路径上是否存在文件或文件夹
  • get_vault_info -获取vault元数据（名称、路径、文件计数、总大小）

航路点集成

  • get_folder_waypoint -从文件夹注释中获取航点块
  • is_folder_note -检查笔记是否为文件夹笔记

链路管理

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

安装

来自黑曜石社区插件

注： 此插件正在等待社区插件目录的批准。一旦获得批准，即可一键安装。

可用时：

  1. 打开黑曜石设置→ 社区插件
  2. 选择 浏览 并搜索“MCP服务器”
  3. 点击 安装
  4. 启用插件

来源

先决条件： Node.js和npm必须安装在您的系统上。

  1. 将此存储库克隆到vault的插件文件夹中：

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

  2. 安装依赖项：

    npm install

  3. 构建插件：

    npm run build

  4. 在黑曜石设置中启用插件→ 社区插件

配置

  1. 打开黑曜石设置→ MCP服务器

  2. 配置以下选项：

    • 端口：HTTP服务器端口（默认值：3000）
    • 自动启动：黑曜石启动时自动启动服务器
    • API密钥：自动生成的加密身份验证令牌（可以在设置中重新生成）

  3. 单击“启动服务器”或使用功能区图标切换服务器

认证

API密钥在您首次安装插件时自动生成，并使用系统的安全凭据存储（macOS钥匙串、Windows凭据管理器、Linux密钥服务（如可用））进行加密。

用法

启动服务器

  • 通过功能区图标：单击左侧边栏中的服务器图标
  • 通过命令面板：运行“启动MCP服务器”
  • 自动启动：在设置中启用以自动启动

连接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密钥：

  1. 打开黑曜石设置→ MCP服务器
  2. 查找 API密钥 “身份验证”部分中的字段
  3. 单击复制图标将API密钥复制到剪贴板
  4. 替换 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": "# New Note\n\nThis is the content."
    }
  }
}

搜索笔记

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

故障排除

服务器无法启动

端口已在使用中：

  • 另一个应用程序正在使用端口3000
  • 在设置中更改端口→ MCP服务器→ Port
  • 常见替代品：3001、8080、8000

权限被拒绝：

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

身份验证失败

无效的API密钥：

  • 从“设置”中再次复制API密钥→ MCP服务器
  • 确保包含完整密钥，没有多余空格
  • 尝试使用“重新生成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）是否有错误消息

未生效的更改：

  • 重新加载黑曜石（Ctrl/Cmd+R）
  • 如果从源头建造，请确保 npm run build 成功完成

安全考虑

该插件实现了多个安全层：

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

发展

从源头构建

npm install
npm run dev    # Watch mode for development
npm run build  # Production build
  • 对以下内容进行更改 main.ts （或创建新 .ts 文件）。这些更改应自动编译为 main.js.
  • 重新加载Obsidian以加载插件的新版本。
  • 在设置窗口中启用插件。
  • 用于更新Obsidian API运行 npm update 在repo文件夹下的命令行中。

贡献

欢迎投稿！请查看 贡献指南 有关以下内容的详细信息：

  • 开发设置和工作流程
  • 代码风格和架构指南
  • 测试要求
  • 拉取请求流程
  • 放行程序

贡献者快速入门

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 通过测试进行更改
  4. 跑 npm test 和 npm run build
  5. 提交您的更改
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

报告问题

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

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

报告错误时，请包括：

  • 黑曜石版本
  • 插件版本
  • 操作系统
  • 重现问题的步骤
  • 来自开发人员控制台的任何错误消息（Ctrl+Shift+I）

支持

如果你觉得这个插件有用，可以考虑支持它的开发：

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

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

许可证

该项目根据MIT许可证获得许可。有关完整的许可证详细信息，请参阅存储库。

相关 MCP