黑曜石mcp超
一个高性能的MCP（模型上下文协议）服务器，将黑曜石库作为结构化、可查询的知识图公开给AI代理。使用 黑名单本地REST API 插件与黑曜石通信，确保与插件、同步和实时编辑完全兼容。
先决条件
- 黑曜石 已安装并正在运行
- 本地REST API 在Obsidian中安装并启用插件
- 从Obsidian设置>本地REST API复制API密钥
特性
- 🔍 语义分析：从Markdown中提取原子语义单位（链接、反向链接、标签、标题）
- 🕸️ 知识图谱：构建和维护vault的图形表示
- ⚡ 低延迟：用于快速检索的内存缓存
- 🔐 安全编辑：通过Obsidian的API进行双向读/写操作
- 🎯 上下文注入：代理工作流的范围上下文
- 📊 丰富的查询：按内容、标签和图形结构搜索
- 🔌 插件感知：通过Obsidian工作，尊重插件、同步和元数据
安装
npm install obsidian-mcp-ultra用法
作为独立服务器
# Run with API key
OBSIDIAN_API_KEY=your-api-key obsidian-mcp-ultra
# Or pass API key as argument
obsidian-mcp-ultra your-api-key
# Custom API URL (default: http://127.0.0.1:27123)
OBSIDIAN_API_URL=http://localhost:27123 OBSIDIAN_API_KEY=your-api-key obsidian-mcp-ultra作为MCP服务器（克劳德桌面）
添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"obsidian-mcp-ultra": {
"command": "node",
"args": [
"/path/to/obsidian-mcp-ultra/dist/index.js"
],
"env": {
"OBSIDIAN_API_URL": "http://127.0.0.1:27123",
"OBSIDIAN_API_KEY": "your-api-key-here"
}
}
}
}可用工具
search_notes
按内容、标题或标签搜索笔记。
参数：
query（string）：搜索查询limit（数字，可选）：最大结果（默认值：10）
read_note
阅读笔记的完整内容和元数据。
参数：
path（string）：注释的路径（相对于vault根）
create_note
在vault中创建新注释。
参数：
path（string）：新注释的路径content（string）：注释内容
update_note
更新现有注释。
参数：
path（string）：注释路径content（string）：新内容
list_notes
列出vault中的所有笔记。
get_backlinks
获取链接到特定笔记的所有笔记。
参数：
path（string）：注释路径
get_graph
获取知识图结构。
参数：
path（string，可选）：获取特定注释的连接节点depth（数字，可选）：连接深度（默认值：1）
find_by_tag
查找具有特定标签的所有笔记。
参数：
tag（string）：要搜索的标签
get_stats
获取vault统计信息（总笔记、链接、标签等）
可用资源
obsidian://vault/all-notes
vault中所有笔记的列表（JSON）
obsidian://vault/graph
完整的知识图结构（JSON）
obsidian://vault/stats
保险库统计信息（JSON）
obsidian://note/{path}
个人笔记内容（Markdown）
可用提示
summarize_note
生成注释及其连接的摘要。
论据：
path（string）：注释路径
find_connections
发现笔记之间的联系。
论据：
note1（string）：第一个音符路径note2（string）：第二个音符路径
建筑
obsidian-mcp-ultra
├── Parser Layer
│ └── Extracts frontmatter, links, tags, headings
├── Vault Interface
│ └── Obsidian REST API client with caching
├── Graph Builder
│ └── Constructs and queries knowledge graph
└── MCP Server
├── Tools (actions)
├── Resources (data access)
└── Prompts (templates)发展
# Install dependencies
npm install
# Build
npm run build
# Run in development mode (requires Obsidian + Local REST API plugin)
OBSIDIAN_API_KEY=your-key npm run dev
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Type checking
npm run lint保险库结构示例
my-vault/
├── daily/
│ ├── 2024-01-01.md
│ └── 2024-01-02.md
├── projects/
│ ├── project-a.md
│ └── project-b.md
└── index.md支持的Markdown功能
- 维基链接:
[[Note Name]]或[[Note Name|Display Text]] - Markdown链接:
[Display Text](path/to/note.md) - 标签:
#tag或#nested/tag - 前台：文件顶部的YAML元数据
- 标题:
# H1通过###### H6
演出
- 缓存：解析后的笔记缓存在内存中
- 增量更新：只有修改过的笔记才会被重新解析
- 延迟加载：按需解析笔记
- 图索引：用于快速查询的预构建图结构
安全
- API密钥验证：所有请求都通过Bearer令牌进行身份验证
- 无直接文件系统访问：所有操作都通过Obsidian的REST API
- 无代码执行：无动态代码执行或eval
- 默认情况下为只读：写入操作需要显式的工具调用
许可证
麻省理工学院
贡献
欢迎投稿！请打开问题或PR。
链接
验证
快速验证测试
安装后，验证服务器是否正常工作：
# Build the project
npm run build
# Run tests
npm test
# Test with a live Obsidian vault (requires Local REST API plugin)
OBSIDIAN_API_KEY=your-key npx tsx examples/test-vault.ts所有测试应通过，保险库应成功查询。
MCP服务器测试
直接测试MCP服务器：
# Start the server
OBSIDIAN_API_KEY=your-key node dist/index.js服务器应输出：
Connected to Obsidian REST API
Building vault graph...
Graph built successfully
Obsidian MCP Ultra server running on stdio按Ctrl+C停止服务器。
故障排除
常见问题
问题： Cannot connect to Obsidian REST API 解决方案： 确保Obsidian在启用本地REST API插件的情况下运行
问题： Cannot authenticate with Obsidian REST API (HTTP 401) 解决方案： 检查你的 OBSIDIAN_API_KEY 匹配“Obsidian设置”>“本地REST API”中的键
问题： Cannot find module '@modelcontextprotocol/sdk' 解决方案： 跑 npm install 安装依赖项
问题： TypeScript编译错误 解决方案： 跑 npm run build 编译TypeScript
问题： 测试失败 解决方案： 使用清除构建缓存 rm -rf dist && npm run build
版本历史记录
v1.0.0（2024-02-15）
- 初始版本
- 完全支持MCP协议
- 9个工具、4个资源、2个提示
- 知识图实现
- 缓存和性能优化
- 全面的测试套件
- 完整的文件