使用说明

🎛️ 黑曜石主控MCP

黑曜石最全面的MCP服务器 --46种工具，涵盖vault操作、高级搜索、Base（数据库）、Canvas（可视化图形）、定期注释、命令等。

🔥 为什么是这个？

功能	黑曜石主控	mcp黑曜岩	黑曜石mcp服务器	黑曜岩mcp	史密斯mcp黑曜石
工具总数	46	7	8	12	~3
语言	Python	Python	TypeScript	TypeScript
基地支持	✅ 完整CRUD	❌	❌	❌	❌
帆布支架	✅ 13个工具+图形分析	❌	❌	❌	❌
简单搜索	✅	✅	✅	✅	✅
JsonLogic搜索	✅	❌	❌	❌	❌
数据视图DQL	✅	❌	❌	❌	❌
周期性笔记	✅ 5工具	❌	✅ （目标）	❌	❌
活动文件操作	✅ 5工具	❌	✅ （目标）	❌	❌
命令执行	✅	❌	❌	❌	❌
文档结构图	✅	❌	❌	❌	❌
补丁操作	✅ （标题/块/正文）	✅	✅	❌	❌
在黑曜石中打开	✅	❌	❌	❌	❌
需要REST API插件	✅	✅	✅	❌ （文件系统）	❌ （文件系统）
异步/类型化	✅ httpx+Pydantic	✅	✅	✅	-

📋 先决条件

1.安装Obsidian本地REST API插件

此MCP服务器通过以下方式与Obsidian通信 本地REST API 社区插件。

开放式黑曜石→ 设置→ 社区插件
点击浏览并搜索 “本地REST API”
安装和启用插件
转到插件设置，然后：
- 复制您的 API密钥 （你需要这个）
- 注意端口（默认值： 27124 对于HTTPS， 27123 对于HTTP）
- 可选地启用HTTPS（推荐）

📖 插件仓库：科丁顿熊/黑曜石本地休息api

2.Python环境

pip install httpx pydantic mcp

或者使用需求文件：

pip install -r requirements.txt

⚙️ 配置

设置这些环境变量：

# Required
export OBSIDIAN_API_KEY="your-api-key-from-plugin-settings"

# Optional (defaults shown)
export OBSIDIAN_HOST="127.0.0.1"
export OBSIDIAN_PORT="27124"
export OBSIDIAN_USE_HTTPS="true"
export OBSIDIAN_VERIFY_SSL="false"  # Set to false for self-signed cert

或者创建一个 .env 文件（参见 .env.example).

🛠️ 全部46个工具

📊 系统

工具	说明
`obsidian_get_server_status`	获取REST API服务器状态和身份验证状态

📁 保险库操作（9个工具）

工具	说明
`obsidian_list_files`	列出目录中的文件/文件夹
`obsidian_get_file`	获取文件内容（markdown或带frontmatter的JSON）
`obsidian_create_file`	创建新文件
`obsidian_update_file`	替换整个文件内容
`obsidian_append_to_file`	将内容附加到文件末尾
`obsidian_patch_file`	补丁特定部分（标题/块/正面）
`obsidian_delete_file`	删除文件
`obsidian_get_document_map`	获取文档结构（标题、块、正文）
`obsidian_open_file`	在Obsidian UI中打开文件（可选行号）

📝 活动文件操作（5个工具）

工具	说明
`obsidian_get_active_file`	获取当前打开的文件内容
`obsidian_update_active_file`	替换活动文件内容
`obsidian_append_to_active_file`	附加到活动文件
`obsidian_patch_active_file`	活动文件的补丁部分
`obsidian_delete_active_file`	删除活动文件

🔍 搜索（3个工具）

工具	说明
`obsidian_simple_search`	跨vault的基本文本搜索
`obsidian_dataview_search`	类似SQL的Dataview DQL查询（需要Dataview插件）
`obsidian_jsonlogic_search`	支持glob/regexp的JsonLogic查询

⚡ 命令（2个工具）

工具	说明
`obsidian_list_commands`	列出所有可用的黑曜石命令
`obsidian_execute_command`	按ID执行任何黑曜石命令

📅 定期笔记（5个工具）

工具	说明
`obsidian_get_periodic_note`	获取每日/每周/每月/每季度/每年的备注
`obsidian_update_periodic_note`	更新定期笔记内容
`obsidian_append_to_periodic_note`	附于定期注释
`obsidian_patch_periodic_note`	定期票据的补丁部分
`obsidian_delete_periodic_note`	删除定期注释

🗃️ 基础--数据库视图（8个工具）

工具	说明
`obsidian_list_bases`	列出vault中的所有.base文件
`obsidian_get_base`	获取基本配置和视图
`obsidian_create_base`	使用表格/看板视图创建新基地
`obsidian_update_base`	更新基本配置
`obsidian_delete_base`	删除基础文件
`obsidian_query_base_entries`	查询与基本筛选器匹配的笔记
`obsidian_add_entry_to_base`	为基础创建带有属性的注释
`obsidian_update_entry_properties`	在笔记上更新frontmatter属性

🎨 画布——可视化节点图（14个工具）

工具	说明
`obsidian_list_canvases`	列出vault中的所有.canvas文件
`obsidian_get_canvas`	获取包含所有节点和边的完整画布
`obsidian_create_canvas`	创建新的空画布
`obsidian_delete_canvas`	删除画布文件
`obsidian_add_canvas_node`	添加节点（文本、文件、链接或组）
`obsidian_update_canvas_node`	更新节点属性（位置、大小、内容、颜色）
`obsidian_remove_canvas_node`	删除节点及其连接边
`obsidian_add_canvas_edge`	在节点之间添加边（连接）
`obsidian_update_canvas_edge`	更新边缘属性（边、箭头、标签、颜色）
`obsidian_remove_canvas_edge`	移除边缘
`obsidian_batch_canvas_update`	在一个读/写周期内批处理多个节点/边缘操作
`obsidian_canvas_overview`	获取图分析（DAG检测、组件、连接）
`obsidian_search_canvas_nodes`	使用过滤器搜索节点，返回子图
`obsidian_get_canvas_subgraph`	提取特定节点及其连接

🔍 搜索比较

简单搜索

基本全文搜索。不需要插件。

query: "meeting notes"

JsonLogic搜索

使用glob和regexp进行强大的基于JSON的查询。 不需要插件。

{"and": [
  {"glob": ["Projects/*.md", {"var": "path"}]},
  {"===": [{"var": "frontmatter.status"}, "active"]}
]}

数据视图DQL搜索

用于复杂查询的类似SQL的语法。 需要Dataview插件。

TABLE status, due FROM "Projects" WHERE status = "active" SORT due ASC

🗃️ 基础：类似数据库的视图

黑曜石基座允许您使用frontmatter属性在笔记上创建动态视图（表、kanbans）。此MCP服务器提供 完全CRUD支持 对于Bases来说，这是其他MCP服务器所没有的功能。

示例：创建项目跟踪器

# Create a base with table and kanban views
obsidian_create_base({
    "name": "Projects",
    "source_folder": "Projects",
    "views": [
        {
            "name": "All Projects",
            "view_type": "table",
            "fields": ["status", "priority", "due_date"]
        },
        {
            "name": "Kanban",
            "view_type": "cards",
            "group_by": "status"
        }
    ]
})

# Add entries with structured properties
obsidian_add_entry_to_base({
    "base_name": "Projects",
    "title": "Build MCP Server",
    "properties": {
        "status": "in-progress",
        "priority": "high",
        "due_date": "2024-02-15"
    }
})

🎨 画布：可视化节点图

黑曜石画布允许您创建具有由边连接的节点（文本、文件、链接、组）的无限空间画布。此MCP服务器提供 全画布操作 加 图分析 --其他MCP服务器没有提供的功能。

节点类型

类型	描述	关键字段
`text`	Markdown文本内容	`text`
`file`	嵌入vault文件	`file`, `subpath` （可选标题/块）
`link`	嵌入web URL	`url`
`group`	用于组织节点的可视化容器	`label`

示例：构建知识图谱

# Create a canvas
obsidian_create_canvas({"path": "Knowledge Graph.canvas"})

# Add concept nodes
obsidian_add_canvas_node({
    "path": "Knowledge Graph.canvas",
    "node_type": "text",
    "text": "# Machine Learning\nCore concepts and techniques",
    "x": 0, "y": 0,
    "width": 300, "height": 100,
    "color": "4"  # Green preset
})

obsidian_add_canvas_node({
    "path": "Knowledge Graph.canvas",
    "node_type": "text", 
    "text": "# Neural Networks",
    "x": 400, "y": 0,
    "color": "4"
})

# Connect them with a labeled edge
obsidian_add_canvas_edge({
    "path": "Knowledge Graph.canvas",
    "from_node": "<node1_id>",
    "to_node": "<node2_id>",
    "label": "includes",
    "to_end": "arrow"
})

# Embed an existing note
obsidian_add_canvas_node({
    "path": "Knowledge Graph.canvas",
    "node_type": "file",
    "file": "Notes/Deep Learning.md",
    "x": 400, "y": 200
})

批量操作（高效）

使用 obsidian_batch_canvas_update 要在单个读/写周期中应用多个更改：

obsidian_batch_canvas_update({
    "path": "Architecture.canvas",
    "add_nodes": {
        "api": {"node_type": "text", "x": 0, "y": 0, "text": "# API Layer"},
        "db": {"node_type": "text", "x": 300, "y": 0, "text": "# Database"},
        "cache": {"node_type": "text", "x": 150, "y": 150, "text": "# Cache"}
    },
    "add_edges": {
        "e1": {"from_node": "api", "to_node": "db", "label": "queries"},
        "e2": {"from_node": "api", "to_node": "cache", "label": "reads"},
        "e3": {"from_node": "cache", "to_node": "db", "label": "misses"}
    }
})
# Returns node_id_mapping: {"api": "a1b2..", "db": "c3d4..", "cache": "e5f6.."}

Dict键充当temp_ids——边可以引用在同一批中创建的节点。

图形分析

这 obsidian_canvas_overview 该工具提供强大的图形分析功能：

obsidian_canvas_overview({"path": "Knowledge Graph.canvas"})

# Returns:
{
    "total_nodes": 15,
    "nodes_by_type": {"text": 8, "file": 5, "group": 2},
    "total_edges": 12,
    "is_dag": true,           # Directed Acyclic Graph detection
    "has_cycles": false,
    "connected_components": 1, # All nodes are connected
    "isolated_nodes": 0,
    "most_connected_nodes": [
        {"id": "abc123", "type": "text", "connections": 5, "preview": "Machine Learning"}
    ],
    "leaf_nodes": 4,          # Nodes with no outgoing edges
    "root_nodes": 1,          # Nodes with no incoming edges
    "groups": [
        {"id": "grp1", "label": "Core Concepts", "node_count": 6}
    ]
}

搜索和筛选

# Find all text nodes containing "TODO"
obsidian_search_canvas_nodes({
    "path": "Project.canvas",
    "query": "TODO|FIXME",
    "node_types": ["text"]
})

# Find nodes connected to a specific node
obsidian_search_canvas_nodes({
    "path": "Project.canvas",
    "connected_to": "abc123",
    "expand_depth": 2  # Include neighbors up to 2 hops away
})

# Extract a subgraph of specific nodes
obsidian_get_canvas_subgraph({
    "path": "Project.canvas",
    "node_ids": ["node1", "node2", "node3"],
    "include_internal_edges": true
})

⚠️ 备注：如果在Obsidian的UI中打开画布，则Obsidian在同步时可能会覆盖API更改。在进行程序更改之前关闭画布。

🚀 用法

使用克劳德桌面

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian-master-control-mcp/mcp_server.py"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "OBSIDIAN_USE_HTTPS": "true",
        "OBSIDIAN_VERIFY_SSL": "false"
      }
    }
  }
}

使用测试代理

包含用于交互式测试的测试代理：

# Set environment variables first
export OBSIDIAN_API_KEY="your-key"
export OPENROUTER_API_KEY="your-openrouter-key"  # For the agent's LLM

# Run the agent
python agent.py

然后自然地聊天：

> List all my project notes
> Create a new daily note for today
> Search for notes about "machine learning"
> Create a base to track my reading list

📁 项目结构

.
├── mcp_server.py          # MCP server with 46 tools
├── obsidian_client.py     # Core REST API client
├── bases_client.py        # Bases operations client
├── canvas.py              # Canvas models + graph analysis
├── canvas_operations.py   # Canvas high-level operations
├── agent.py               # Test agent for interactive use
├── agents/
│   └── obsidian.md        # Agent system prompt
├── docs/
│   └── changelog.md       # Version history
├── requirements.txt
└── .env.example

📜 许可证

MIT许可证——随意使用。

🙏 致谢

黑曜石 --令人难以置信的知识库应用程序
本地REST API插件 --使这一切成为可能
模型上下文协议 --MCP标准