黑曜石MCP桥
用于黑曜石的WebSocket和MCP服务器-第一阶段基础设施
通过模型上下文协议为AI客户端直接API访问Obsidian。
🎯 概述
Obsidian MCP桥提供了一个在Obsidian内部运行的WebSocket服务器，该服务器通过模型上下文协议（MCP）向AI客户端公开vault API。这使得像Claude Code和Codex这样的人工智能助手能够以完全的保真度直接访问您的黑曜石金库，包括渲染的数据视图查询、插件集成等。
这提供了什么
- WebSocket服务器 -在Obsidian内部运行，公开vault API
- MCP服务器 -实现MCP协议的Python和Node.js适配器
- 工具注册表 -可扩展的YAML驱动系统，用于添加自定义工具
- 插件集成 -访问数据视图、元数据菜单和其他插件API
第二阶段： 有关作业编排和多代理工作流，请参阅 KANTS插件
主要特点
✅ 可扩展工具系统 -通过YAML添加自定义工具，无需修改插件代码 ✅ 自动发现 -MCP服务器自动检测注册表中的可用工具 ✅ 用户可编写脚本 -在JavaScript/TypeScript中创建自定义处理程序 ✅ 插件集成 -执行数据视图查询、访问元数据菜单等 ✅ 缺省巩固安全 -API密钥身份验证，本地主机绑定
📦 存储库结构
obsidian-mcp-bridge/ # ← Obsidian plugin root
├── manifest.json # Plugin manifest (required at root)
├── main.js # Compiled plugin (required at root)
├── package.json # Plugin dependencies
├── src/ # Plugin source code
│ ├── main.ts # Entry point
│ ├── settings.ts # Settings UI
│ ├── websocket-server.ts # WebSocket server
│ └── tool-registry.ts # Tool registry system
│
├── .mcp-bridge/ # Tool registry
│ ├── tools.yaml # Tool definitions
│ └── handlers/ # Tool handlers
│ ├── core/ # Built-in handlers
│ └── user/ # Custom user handlers
│
├── servers/ # MCP Servers
│ ├── python-old/ # Python MCP server
│ │ ├── obsidian_mcp_server.py
│ │ └── obsidian_mcp_server_auto.py
│ │
│ └── node-old/ # Node.js MCP server
│ ├── src/
│ └── package.json
│
└── docs/ # Documentation
├── guides/ # User guides
├── architecture/ # Technical architecture
├── development/ # Contributing & publishing
├── features/ # Feature documentation
└── testing/ # Testing guides为什么是这种结构？ 存储库 是 插件- manifest.json 和 main.js 位于根目录，因此您可以将整个仓库放置在 .obsidian/plugins/ 便于测试和开发。
建筑
AI Client → MCP Server (Python/Node) → WebSocket → Obsidian Plugin → Obsidian APIs
↓
YAML Tool Registry
↓
User Handler Scripts🚀 快速开始
插件安装
方法1：直接复制（用于生产）
# Copy entire repo to plugins directory
cp -r /obsidian-mcp-bridge /.obsidian/plugins/
# Or on Windows:
xcopy "\obsidian-mcp-bridge" ^
"\.obsidian\plugins\obsidian-mcp-bridge" /E /I方法2:Symlink（用于开发）
# Windows PowerShell
New-Item -ItemType SymbolicLink `
-Path "\.obsidian\plugins\obsidian-mcp-bridge" `
-Target "\obsidian-mcp-bridge"
# Linux/macOS
ln -s /obsidian-mcp-bridge /.obsidian/plugins/在中启用插件 黑曜石设置→ 社区插件
构建插件
cd obsidian-mcp-bridge
npm install
npm run build # Compiles TypeScript → main.js at root
# Development mode (auto-rebuild on changes)
npm run dev配置MCP服务器
Python服务器（建议用于自动发现）：
cd servers/python-old
pip install -r requirements.txt
# Set API key (get from plugin settings)
export OBSIDIAN_MCP_KEY="your-api-key-here"
# Run auto-discovery server
python obsidian_mcp_server_auto.py节点服务器（备选）：
cd servers/node-old
npm install
npm run build
npm start连接AI客户端
克劳德代码：
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%/Claude/claude_desktop_config.json (Windows)
{
"mcpServers": {
"obsidian": {
"command": "python",
"args": ["/obsidian-mcp-bridge/servers/python-old/obsidian_mcp_server_auto.py"],
"env": {
"OBSIDIAN_MCP_KEY": "your-api-key-from-plugin-settings"
}
}
}
}食品法典：
# ~/.codex/config.toml
[[servers]]
name = "obsidian-bridge"
command = "python"
args = ["/obsidian-mcp-bridge/servers/python-old/obsidian_mcp_server_auto.py"]
env = { OBSIDIAN_MCP_KEY = "your-api-key-from-plugin-settings" }注： 使用绝对路径。自动发现服务器(_auto.py)建议使用，因为它会自动检测插件中的所有可用工具。文档
指南：
架构：
特征：
发展：
测试：
配置
插件设置
- 主持人：
127.0.0.1（默认情况下仅限本地主机） - 端口：
27125 - API密钥： 自动生成（复制到MCP服务器配置）
- 需要身份验证：
true（所有连接都需要API密钥）
MCP服务器环境变量
OBSIDIAN_HOST=localhost # Plugin host
OBSIDIAN_PORT=27125 # Plugin port
OBSIDIAN_USE_SSL=false # Use wss:// instead of ws://
OBSIDIAN_MCP_KEY= # API key from plugin settings可扩展性
MCP网桥使用 基于YAML的工具注册表 它允许用户在不修改插件代码的情况下添加自定义功能。
示例：添加自定义工具
1.创建处理程序脚本：
// .mcp-bridge/handlers/user/my_tool.js
module.exports = {
async execute(params, context) {
const { app } = context;
const files = app.vault.getMarkdownFiles();
return { totalFiles: files.length };
}
};2.添加到tools.yaml：
tools:
user:
- name: count_notes
description: Count total notes in vault
handler: user/my_tool.js
inputSchema:
type: object
properties: {}3.插件自动重新加载 -AI助手可以立即使用该工具！
📖 完整的可扩展性指南 通过示例和最佳实践。
安全
当前（仅限本地主机）
- WebSocket绑定到
127.0.0.1仅 - API密钥验证
- 无需SSL（本地流量）
- 用户脚本运行时只能访问Obsidian API
沙箱
用户处理程序脚本可以访问：
- ✅ 黑眼圈API(
app,vault,workspace) - ✅ 插件API（数据视图、元数据菜单等）
- ❌ Node.js文件系统(
fs,path) - ❌ 网络请求(
http,https,fetch) - ❌ 进程产卵(
child_process)
看 可扩展性指南-安全 了解详情。
许可证
麻省理工学院