黑曜石-MCP

Name: 黑曜石-MCP
Author: aleksakarac

作者：aleksakarac2 星标更新：2025-10-23

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

项目介绍

Obsidian MCP Extended

一个全面的Obsidian MCP服务器，包含45个工具，覆盖混合文件系统原生和API基础架构。扩展了obsidian-mcp，增加了高级插件控制、反向链接、标签管理和分析功能。

注意：此项目扩展了基础的obsidian-mcp服务器。原始的README被保留为README.upstream.md。

🌟 功能

混合架构

文件系统原生工具（33个工具） - 完全离线工作，无需Obsidian：

✅ 直接文件访问以获得最大性能
✅ 不需要任何Obsidian插件
✅ 即时启动，内存占用极低
✅ 全面离线能力

API基础工具（12个工具） - 当Obsidian运行时增强的功能：

🔌 实时工作区控制
🔌 高级插件集成（模板器，Dataview DQL）
🔌 命令面板访问
🔌 需要本地REST API插件

📦 完整工具列表（45个工具）

🔗 反向链接分析（2个工具 - 文件系统）

get_backlinks_fs - 查找所有链接到特定笔记的笔记
get_broken_links_fs - 识别保险库中的损坏链接

🏷️ 标签管理（4个工具 - 文件系统）

analyze_note_tags_fs - 提取前言和内联标签
add_tag_fs - 向笔记前言添加标签
remove_tag_fs - 从前言中移除标签
search_by_tag_fs - 通过标签查找笔记

✏️ 智能内容插入（4个工具 - 文件系统）

insert_after_heading_fs - 在特定标题后插入内容
insert_after_block_fs - 在块引用后插入内容
update_frontmatter_field_fs - 更新/添加前言字段
append_to_note_fs - 在笔记末尾追加内容

📊 统计与分析（2个工具 - 文件系统）

note_statistics_fs - 个别笔记的综合统计信息
vault_statistics_fs - 聚合保险库统计信息

✅ 任务插件（5个工具 - 文件系统）

search_tasks - 使用表情元数据搜索任务（📅⏫🔁✅）
create_task - 创建带有元数据的任务
toggle_task_status - 切换完成/未完成状态
update_task_metadata - 更新截止日期、优先级和重复性
get_task_statistics - 任务完成情况分析

📊 Dataview内联字段（4个工具 - 文件系统）

extract_dataview_fields - 解析所有语法变体（::, [], ()）
search_by_dataview_field - 通过字段值查找笔记
add_dataview_field - 添加内联字段
remove_dataview_field - 移除内联字段

📋 看板（5个工具 - 文件系统）

parse_kanban_board - 解析markdown看板结构
add_kanban_card - 向列中添加卡片
move_kanban_card - 在列之间移动卡片
toggle_kanban_card - 切换卡片完成状态
get_kanban_statistics - 看板分析

🔗 增强链接跟踪（5个工具 - 文件系统）

get_link_graph - 完整的保险库链接图
find_orphaned_notes - 识别孤立的笔记
find_hub_notes - 寻找高度连接的笔记
analyze_link_health - 保险库连接度量
get_note_connections - 多级连接探索

🎨 画布文件（5个工具 - 文件系统）

parse_canvas - 解析JSON画布v1.0文件
add_canvas_node - 添加文本/文件节点
add_canvas_edge - 用边连接节点
remove_canvas_node - 删除节点
get_canvas_node_connections - 分析节点关系

📝 模板（3个工具 - 文件系统）

expand_template - 简单的{{变量}}扩展
create_note_from_template_fs - 离线应用模板
list_templates - 浏览可用模板

🔌 Dataview查询API（4个工具 - 需要Obsidian + Dataview）

execute_dataview_query - 执行完整的DQL查询（LIST/TABLE/TASK）
list_notes_by_tag_dql - 基于标签的DQL查询
list_notes_by_folder_dql - 基于文件夹的DQL查询
table_query_dql - 创建表格数据视图

🔌 模板器插件API（3个工具 - 需要Obsidian + 模板器）

render_templater_template - 动态模板渲染
create_note_from_template_api - 从模板器模板创建笔记
insert_templater_template - 在光标处插入模板

🔌 工作区管理（6个工具 - 需要Obsidian）

get_active_file - 获取当前活动文件
open_file - 在Obsidian中打开文件
close_active_file - 关闭当前文件
navigate_back - 在历史记录中向后导航
navigate_forward - 在历史记录中向前导航
toggle_edit_mode - 切换编辑/预览模式

🔌 命令执行（3个工具 - 需要Obsidian）

execute_command - 运行Obsidian命令
list_commands - 列出所有可用命令
search_commands - 通过名称/ID搜索命令

🚀 快速开始

先决条件

# 需要Python 3.11+
python --version

# 安装uv（推荐的包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh

安装

# 克隆仓库
git clone https://github.com/aleksakarac/obsidian-mcp.git
cd obsidian-mcp

# 使用uv安装（推荐）
uv pip install .

# 或使用pip
pip install .

配置

仅文件系统工具（不需要Obsidian）

在Claude Code配置中添加（~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/绝对路径/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/路径/to/你的/obsidian/保险库"
      }
    }
  }
}

完整混合模式（文件系统 + API工具）

在Obsidian中安装本地REST API插件
配置插件设置：
- 启用HTTPS：否（使用HTTP进行localhost）
- API密钥：生成安全密钥
- 端口：27124（默认）
更新Claude Code配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/绝对路径/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/路径/to/你的/obsidian/保险库",
        "OBSIDIAN_REST_API_KEY": "你的-api-key-这里",
        "OBSIDIAN_API_URL": "http://localhost:22714"
      }
    }
  }
}

📖 使用示例

任务插件（文件系统原生）

# 搜索高优先级未完成任务
search_tasks(
    status="未完成",
    priority="高",
    sort_by="截止日期",
    limit=10
)

# 创建带有元数据的任务
create_task(
    file_path="项目/当前.md",
    content="审查PR #123",
    priority="高",
    due_date="2025-11-01",
    tags=["代码审查", "紧急"]
)

Dataview字段（文件系统原生）

# 提取所有内联字段
extract_dataview_fields(file_path="项目笔记.md")

# 查找状态=活跃的笔记
search_by_dataview_field(
    field_name="状态",
    field_value="活跃"
)

看板（文件系统原生）

# 解析看板结构
parse_kanban_board(file_path="看板/冲刺.md")

# 在列之间移动卡片
move_kanban_card(
    file_path="看板/冲刺.md",
    card_text="实现身份验证",
    from_column="待办事项",
    to_column="进行中"
)

链接分析（文件系统原生）

# 查找孤立的笔记
find_orphaned_notes()

# 获取链接图
get_link_graph()

# 分析保险库健康状况
analyze_link_health()

Dataview查询（需要Obsidian）

# 执行DQL查询
execute_dataview_query(
    query="TABLE 状态, 截止日期 FROM #项目 WHERE 状态 = '活跃'"
)

工作区控制（需要Obsidian）

# 打开文件
open_file(file_path="日常/2025-10-22.md")

# 获取活动文件
get_active_file()

# 执行命令
execute_command(command_id="编辑器:切换粗体")

🏗️ 架构

混合设计哲学

文件系统优先方法：

一切可以是文件系统原生的，都是文件系统原生的
直接文件访问用于读写markdown
核心功能零依赖于Obsidian插件
完全离线能力

API增强：

API工具补充文件系统工具
提供没有Obsidian就无法实现的功能（工作区UI，命令执行）
使插件集成成为可能（模板器，Dataview DQL）
清晰错误消息的优雅降级

技术栈

FastMCP：MCP协议实现
Pydantic：类型安全的数据模型和验证
Python标准库：文件系统操作零外部依赖
httpx：异步HTTP客户端用于API工具

性能

文件系统工具：

1,000笔记：<3秒完成整个保险库扫描
单笔记操作：<100毫秒
链接图生成：<10秒处理1,000笔记

API工具：

命令执行：<500毫秒
查询执行：取决于Dataview插件
工作区操作：<200毫秒

🧪 测试

参见TESTING.md获取详细的测试文档。

# 运行所有测试
uv run pytest

# 运行特定测试套件
uv run pytest tests/unit/test_tasks.py -v

# 运行并生成覆盖率报告
uv run pytest --cov=src --cov-report=html

📝 开发

项目结构

obsidian-mcp/
├── src/
│   ├── models/          # Pydantic数据模型
│   ├── tools/           # MCP工具实现
│   ├── utils/           # 共享实用程序（模式，API客户端）
│   └── server.py        # FastMCP服务器及工具注册
├── tests/
│   ├── unit/            # 工具单元测试
│   └── integration/     # 端到端工作流测试
├── specs/               # 特性规范
└── pyproject.toml       # 项目配置

添加新工具

在src/tools/中创建工具模块
如果需要，在src/models/obsidian.py中添加Pydantic模型
在src/server.py中使用@mcp.tool()装饰器注册工具
在tests/unit/中添加单元测试
更新README.md和CHANGELOG.md

🤝 贡献

欢迎贡献！请：

遵循现有的代码风格
为新特性添加测试
更新文档
确保所有测试通过

📄 许可证

MIT许可证 - 详情见LICENSE

🙏 致谢

基础实现：obsidian-mcp
MCP协议：Model Context Protocol
Obsidian：Obsidian.md

📚 额外文档

TESTING.md - 测试指南
CHANGELOG.md - 版本历史
README.upstream.md - 原始obsidian-mcp README
specs/ - 特性规范和设计文档