Obsidian Master Control MCP

🎛️ 黑曜石主控MCP

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

  

______________________________________________________________________

🔥 为什么是这个？

|---------|------------------------|-----------------|----------------------|---------------|--------------------| | 工具总数 | 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 社区插件。

1. 开放式黑曜石→ 设置→ 社区插件
2. 点击 浏览 并搜索 “本地REST API”
3. 安装和 启用 插件
4. 转到插件设置，然后：

- 复制您的 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个工具

📊 系统

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

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

🔍 搜索（3个工具）

⚡ 命令（2个工具）

📅 定期笔记（5个工具）

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

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

______________________________________________________________________

🔍 搜索比较

简单搜索

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

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服务器没有提供的功能。

节点类型

示例：构建知识图谱

# 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": "",
    "to_node": "",
    "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标准