Obsidian MCP扩展工具集

“Obsidian MCP Extended” 可以翻译为“黑曜石MCP扩展版”。这里，“Obsidian”指的是“黑曜石”，“MCP”可能是一个特定项目、模块或扩展的缩写（具体含义需根据上下文确定），“Extended”表示“扩展版”或“增强版”

一个适用于Obsidian的综合MCP服务器，具备 45个工具 跨越；遍及 混合文件系统原生与API基于 架构。扩展 “obsidian-mcp”可以翻译为“黑曜石-MCP（模组兼容计划）”或根据具体语境简化为“黑曜石MCP”，其中“MCP”通常指的是“Mod Compatibility Pack”（模组兼容包）或类似的模组兼容性计划，具体翻译可能需根据该术语在特定领域的含义进行调整 具备高级插件控制、反向链接管理、标签管理和分析功能。

注这个项目扩展了基础（或：底座/根基） obsidian-mcp 服务器。原始的README文件已保留为 README.upstream.md 翻译为中文是：“上游README文件（Markdown格式）”。

🌟 特点

混合架构

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

• ✅ 直接文件访问以实现最佳性能
• ✅ 无需任何Obsidian插件
• ✅ 瞬时启动，内存占用极低
• ✅ 完全离线功能

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

• 🔌 实时工作空间控制
• 🔌 高级插件集成（Templater，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 - 任务完成分析

📊 数据视图内联字段（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 Canvas 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 - 创建表格数据视图

🔌 Templater 插件 API（3个工具 - 需要 Obsidian + Templater）

• render_templater_template - 动态模板渲染
• create_note_from_template_api - 从Templater模板创建笔记
• 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+ required
python --version

# Install uv (recommended package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

安装

# Clone repository
git clone https://github.com/aleksakarac/obsidian-mcp.git
cd obsidian-mcp

# Install with uv (recommended)
uv pip install .

# Or with pip
pip install .

配置

仅适用于文件系统工具（无需Obsidian）

添加到你的Claude代码配置中（~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

对于全混合模式（文件系统+API工具）

1. 安装 本地REST API插件 在Obsidian中

2. 配置插件设置：

   • 启用HTTPS：否（使用HTTP进行本地主机访问）
   • API密钥：生成一个安全密钥
   • 端口：27124（默认）

3. 更新Claude代码配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "http://localhost:27124"
      }
    }
  }
}

📖 使用示例

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

# Search for high-priority incomplete tasks
search_tasks(
    status="incomplete",
    priority="high",
    sort_by="due_date",
    limit=10
)

# Create task with metadata
create_task(
    file_path="Projects/Current.md",
    content="Review PR #123",
    priority="high",
    due_date="2025-11-01",
    tags=["code-review", "urgent"]
)

数据视图字段（文件系统原生）

# Extract all inline fields
extract_dataview_fields(file_path="Project Notes.md")

# Find notes where status=active
search_by_dataview_field(
    field_name="status",
    field_value="active"
)

看板（原生文件系统）

# Parse board structure
parse_kanban_board(file_path="Boards/Sprint.md")

# Move card between columns
move_kanban_card(
    file_path="Boards/Sprint.md",
    card_text="Implement authentication",
    from_column="To Do",
    to_column="In Progress"
)

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

# Find orphaned notes
find_orphaned_notes()

# Get link graph
get_link_graph()

# Analyze vault health
analyze_link_health()

Dataview 查询（需要 Obsidian）

# Execute DQL query
execute_dataview_query(
    query="TABLE status, due FROM #project WHERE status = 'active'"
)

工作区控制（需要Obsidian）

# Open file
open_file(file_path="Daily/2025-10-22.md")

# Get active file
get_active_file()

# Execute command
execute_command(command_id="editor:toggle-bold")

🏗️ 建筑学

混合设计哲学

以文件系统为先的方法

• 所有可以是文件系统原生的东西，都是文件系统原生的
• 直接文件访问以读写Markdown
• 核心功能不依赖于Obsidian插件
• 完全离线功能

API增强：

• API工具补充了文件系统工具
• 提供仅在Obsidian中才能实现的功能（工作区界面、命令执行）
• 启用插件集成（Templater，Dataview DQL）
• 优雅降级并提供清晰的错误信息

技术栈

• FastMCPMCP协议实现
• **Pydantic（发音类似“派丹尼克”，但根据官方或常见发音习惯，也可直接音译为“皮丹尼克”，不过通常直接使用原名）**具有验证功能的类型安全数据模型
• Python标准库文件系统操作无外部依赖
• httpxAPI工具的异步HTTP客户端

演出

文件系统工具：

• 1000张笔记：全库扫描时间少于3秒
• 单音符操作时间：< 100毫秒
• 链接图生成：1,000个节点耗时少于10秒

API 工具：

• 命令执行时间：< 500毫秒
• 查询执行：依赖于Dataview插件
• 工作区操作：< 200毫秒

🧪 测试

看见 TESTING.md 翻译为中文是：“测试说明文件”或“测试文档” 用于全面的测试文档。

# Run all tests
uv run pytest

# Run specific test suite
uv run pytest tests/unit/test_tasks.py -v

# Run with coverage
uv run pytest --cov=src --cov-report=html

📝 开发

项目结构

obsidian-mcp/
├── src/
│   ├── models/          # Pydantic data models
│   ├── tools/           # MCP tool implementations
│   ├── utils/           # Shared utilities (patterns, API client)
│   └── server.py        # FastMCP server with tool registrations
├── tests/
│   ├── unit/            # Unit tests for tools
│   └── integration/     # End-to-end workflow tests
├── specs/               # Feature specifications
└── pyproject.toml       # Project configuration

添加新工具

1. 在（系统/项目中）创建工具模块 src/tools/
2. 将 Pydantic 模型添加到 src/models/obsidian.py （如需）
3. 在（系统/平台等）中注册工具 src/server.py 和；与 @mcp.tool() 装饰器
4. 添加单元测试 tests/unit/
5. 更新 README.md 和 CHANGELOG.md 文件

🤝 贡献

欢迎投稿！请：

1. 遵循现有的代码风格
2. 为新功能添加测试
3. 更新文档
4. 确保所有测试通过

📄 许可证

MIT 许可证 - 详见 许可证 详情请见

🙏 致谢

• 基础实现： obsidian-mcp 翻译成中文可以是“黑曜石-MCP”（假设MCP是某个特定项目、组织或概念的缩写，这里直接保留原样）。不过，具体翻译可能需要根据MCP在上下文中的具体含义来调整。如果MCP有特定的中文名称或含义，应相应地进行翻译
• MCP协议： 模型上下文协议
• 黑曜石 Obsidian.md（可译为“奥比西迪安笔记”或根据具体语境简化为“Obsidian笔记”，但通常直接保留原名以指代该特定软件）

📚 额外文件

• TESTING.md 翻译为中文是：“测试说明文件”或“测试文档” - 测试指南
• CHANGELOG.md 翻译为中文是：“变更日志.md” 或 “更新记录.md” - 版本历史
• README.upstream.md 翻译为中文是：“README.upstream（上游）文件” - 原始 obsidian-mcp 的 README 文件
• 规格/ - 功能规格和设计文档