使用说明

黑曜石CDP MCP服务器

通过Chrome DevTools协议（CDP）连接到Obsidian，提供MCP工具接口。

特性

与REST API相比，CDP提供了更强大的功能：

功能	CDP	REST API
读/写文件	✅	✅
实时控制台输出	✅	❌
DOM检查/操作	✅	❌
截图	✅	❌
执行任意JS	✅	❌
插件管理	✅	❌
命令执行	✅	✅

先决条件

Obsidian必须在调试模式下启动:

# macOS
open -a Obsidian --args --remote-debugging-port=9222

# Or run directly
/Applications/Obsidian.app/Contents/MacOS/Obsidian --remote-debugging-port=9222

安装

使用npx（无需安装）

你可以使用 npx 无需安装即可直接运行服务器：

npx obsidian-cdp-mcp

全球安装

npm install -g obsidian-cdp-mcp

安装后，您可以使用 obsidian-cdp-mcp 直接命令。

来自源头

git clone https://github.com/QianChenglong/obsidian-cdp-mcp.git
cd obsidian-cdp-mcp
npm install
npm run build
npm link

MCP配置

代码伙伴

添加 ~/.codebuddy/settings.json:

{
  "mcpServers": {
    "obsidian-cdp": {
      "command": "npx",
      "args": ["obsidian-cdp-mcp"],
      "env": {
        "OBSIDIAN_DEBUG_PORT": "9222"
      }
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "obsidian-cdp": {
      "command": "obsidian-cdp-mcp",
      "env": {
        "OBSIDIAN_DEBUG_PORT": "9222"
      }
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-cdp": {
      "command": "npx",
      "args": ["obsidian-cdp-mcp"],
      "env": {
        "OBSIDIAN_DEBUG_PORT": "9222"
      }
    }
  }
}

可用工具

基本操作

工具	说明
`obsidian_get_vault_info`	获取保险库信息
`obsidian_get_active_file`	获取当前打开的文件
`obsidian_read_file`	读取文件内容
`obsidian_write_file`	写入/创建文件
`obsidian_patch_file`	使用搜索和替换应用部分编辑
`obsidian_search`	按路径搜索文件（支持 `path` 限制范围的参数）
`obsidian_search_folders`	按名称或路径搜索文件夹
`obsidian_smart_search`	带同义词规范化的全文搜索（需要Omnisearch插件）
`obsidian_open_file`	打开文件

文件和文件夹管理

工具	说明
`obsidian_list_folder`	列出文件夹内容
`obsidian_create_folder`	创建新文件夹
`obsidian_move_file`	移动或重命名文件/文件夹
`obsidian_delete_file`	删除文件/文件夹

链接和参考

工具	说明
`obsidian_get_backlinks`	获取文件的传入链接
`obsidian_get_outlinks`	从文件中获取传出链接
`obsidian_resolve_link`	解析指向文件路径的wiki链接

元数据和属性

工具	说明
`obsidian_get_tags`	获取标签（保险库范围或每个文件）
`obsidian_search_by_tag`	按标签搜索文件（支持嵌套标签）
`obsidian_get_frontmatter`	获取文件frontmatter/YAML
`obsidian_update_frontmatter`	更新frontmatter属性
`obsidian_get_all_properties`	获取vault中的所有属性名称

编辑操作

工具	说明
`obsidian_get_selection`	获取所选文本
`obsidian_replace_selection`	替换所选文本
`obsidian_insert_at_cursor`	在光标处插入文本
`obsidian_get_cursor_position`	获取光标位置

模板

工具	说明
`obsidian_list_templates`	列出可用模板
`obsidian_apply_template`	将模板应用于文件

插件和命令

工具	说明
`obsidian_list_plugins`	列出所有插件
`obsidian_search_community_plugins`	搜索社区插件库
`obsidian_install_plugin`	从社区存储库安装插件
`obsidian_enable_plugin`	启用已安装的插件
`obsidian_disable_plugin`	禁用已安装的插件
`obsidian_uninstall_plugin`	卸载插件
`obsidian_get_plugin_settings`	获取插件设置
`obsidian_set_plugin_settings`	更新插件设置
`obsidian_list_commands`	列出所有命令
`obsidian_execute_command`	执行命令
`obsidian_dataview_query`	运行Dataview查询（需要Dataview插件）

调试功能（CDP专用）

工具	说明
`obsidian_screenshot`	捕捉黑曜石界面（webp/png/jpeg）
`obsidian_console`	获取控制台输出
`obsidian_eval`	执行任意JavaScript
`obsidian_dom_query`	查询DOM元素

用法示例

截图

{
  "name": "obsidian_screenshot",
  "arguments": { "format": "webp", "quality": 80 }
}

获取控制台日志

{
  "name": "obsidian_console",
  "arguments": { "limit": 20, "type": "error" }
}

执行JavaScript

{
  "name": "obsidian_eval",
  "arguments": {
    "code": "app.workspace.getActiveFile()?.path"
  }
}

搜索文件

{
  "name": "obsidian_search",
  "arguments": { "query": "mcp", "limit": 10 }
}

在特定文件夹中搜索文件

{
  "name": "obsidian_search",
  "arguments": { "query": "config", "path": "技术/kubernetes", "limit": 10 }
}

搜索文件夹

{
  "name": "obsidian_search_folders",
  "arguments": { "query": "work", "limit": 10 }
}

环境变量

变量	默认值	描述
`OBSIDIAN_DEBUG_PORT`	`9222`	黑曜石调试端口

故障排除

未找到黑曜石

确保Obsidian正在调试模式下运行：

curl http://localhost:9222/json

应返回包含黑曜石页面信息的JSON。

连接被拒绝

检查端口是否正确，或者黑曜石是否被防火墙阻止。

许可证

麻省理工学院