AI导哈

Obsidian CLI 管理控制平台

为Obsidian CLI提供受控运行环境的服务器，支持多种配置文件和权限管理，适用于个人和团队的知识管理场景。

  • by amalikn
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 amalikn/obsidian-cli-mcp

使用说明

黑曜石cli-mcp

MCP服务器 黑曜石CLI 具有明确的运行时配置文件，供受管和个人使用。默认配置文件为 governed-readonly; governed-mutation 在读取表面之上添加有界模板和升级工作流，而广泛的遗留表面仅通过显式 personal-unrestricted 轮廓。

需求

  • 黑曜石 桌面应用程序正在运行（macOS、Linux、Windows）
  • 黑曜石CLI 安装：
    • macOS/Linux（通过Homebrew）： brew install obsidianmd/tap/obsidian
    • 窗口：请参见 黑曜石CLI发布
  • Node.js 22+

平台说明： 在macOS上进行了全面测试。Linux是通过相同的Homebrew水龙头（Linuxbrew）支持的。Windows支持未经测试--环境变量注入(HOME/TMPDIR)可能表现不同；欢迎捐款。

安装

无需安装--直接使用运行 npx:

npx -y @joemugen/obsidian-cli-mcp

或全局安装：

npm install -g @joemugen/obsidian-cli-mcp

配置

变量 描述 默认值
OBSIDIAN_BIN Obsidian CLI二进制文件的路径 obsidian
OBSIDIAN_VAULT 默认固定保险库名称 在受管配置文件中是必需的；可选 personal-unrestricted
OBSIDIAN_VAULT_ROOT 固定保险库的规范文件系统根 在受管配置文件中是必需的
OBSIDIAN_POLICY_FILE JSON vault策略文件 受管配置文件中需要
MCP_PROFILE governed-readonly, governed-mutation，或 personal-unrestricted governed-readonly
MCP_TRANSPORT stdio 或 http stdio
MCP_PORT HTTP端口（当 MCP_TRANSPORT=http) 3000
MCP_HTTP_HOST HTTP绑定主机（当 MCP_TRANSPORT=http) 127.0.0.1
MCP_HTTP_AUTH_TOKEN HTTP身份验证的共享承载令牌 受管HTTP和任何远程HTTP绑定都需要
MCP_HTTP_ALLOW_REMOTE_BIND 显式远程绑定选择加入(true) 默认情况下禁用

重要信息（macOS）： 始终指向 OBSIDIAN_BIN 到Homebrew二进制文件($(brew --prefix)/bin/obsidian).Homebrew二进制文件正确地将stdout刷新到管道；普通的应用程序包符号链接则不会。

档案

  • governed-readonly
    • 安全默认值。
    • 注册精确的路径注释/属性读取以及策略过滤的受管发现(obsidian_search, obsidian_search_context，过滤链接，过滤反向链接）。
    • 需要 OBSIDIAN_VAULT, OBSIDIAN_VAULT_ROOT，以及 OBSIDIAN_POLICY_FILE.
    • 禁用每次呼叫保险库覆盖。
  • governed-mutation
    • 在上面添加精确的路径变异表面以及受控模板和升级助手 governed-readonly.
    • 允许精确的路径注释/属性编辑和受管理的工作流工具： obsidian_create_note_from_template, obsidian_create_review_note, obsidian_create_promotion_candidate, obsidian_create_curated_note，以及 obsidian_log_promotion.
    • 块重命名、移动、删除、任务切换、将模板插入活动笔记、每日突变、插件/主题/代码段突变、运行时状态突变和执行/评估表面。
    • 需要与相同的固定保险库和策略输入 governed-readonly.
  • personal-unrestricted
    • 完整遗留界面的兼容性配置文件，包括变异和面向开发人员的工具。
    • 不是默认值。
    • 用于受控的个人使用，而非受控的部署。

受监管的保险库政策

受控配置文件在调用Obsidian CLI之前强制执行真实路径策略：

  • 仅限精确路径注释/属性操作
  • 仅在配置内部进行有界发现 discoveryAllowlist 根
  • 已批准的模板仅在配置内部读取 templateAllowlist 根
  • 审核笔记、促销候选人、策划目的地和促销日志的工作流路由
  • 默认拒绝配置的写入分配列表之外的写入
  • 明确的丹尼支持
  • 隐藏的路径和 .obsidian/** 默认拒绝
  • 针对固定路径的规范化 OBSIDIAN_VAULT_ROOT
  • 可选符号链接遍历拒绝

看 examples/governed-vault-policy.example.json 以保守的第二个大脑为例。

客户端设置

克劳德桌面

编辑操作系统的配置文件：

操作系统 路径
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json
窗户 %APPDATA%\Claude\claude_desktop_config.json 
{
  "mcpServers": {
    "obsidian-cli": {
      "command": "npx",
      "args": ["-y", "@joemugen/obsidian-cli-mcp"],
      "env": {
        "MCP_PROFILE": "governed-readonly",
        "OBSIDIAN_BIN": "/opt/homebrew/bin/obsidian",
        "OBSIDIAN_VAULT": "MyVault",
        "OBSIDIAN_VAULT_ROOT": "/path/to/MyVault",
        "OBSIDIAN_POLICY_FILE": "/path/to/governed-vault-policy.json"
      }
    }
  }
}

保存后重新启动Claude Desktop。

克劳德代码

添加到您的项目 .mcp.json （或 ~/.claude/mcp.json 全球）：

{
  "mcpServers": {
    "obsidian-cli": {
      "command": "npx",
      "args": ["-y", "@joemugen/obsidian-cli-mcp"],
      "env": {
        "MCP_PROFILE": "governed-readonly",
        "OBSIDIAN_BIN": "/opt/homebrew/bin/obsidian",
        "OBSIDIAN_VAULT": "MyVault",
        "OBSIDIAN_VAULT_ROOT": "/path/to/MyVault",
        "OBSIDIAN_POLICY_FILE": "/path/to/governed-vault-policy.json"
      }
    }
  }
}

或者直接从CLI添加：

claude mcp add obsidian-cli --transport stdio \
  -e MCP_PROFILE=governed-readonly \
  -e OBSIDIAN_BIN=/opt/homebrew/bin/obsidian \
  -e OBSIDIAN_VAULT=MyVault \
  -e OBSIDIAN_VAULT_ROOT=/path/to/MyVault \
  -e OBSIDIAN_POLICY_FILE=/path/to/governed-vault-policy.json \
  -- npx -y @joemugen/obsidian-cli-mcp

光标

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "obsidian-cli": {
      "command": "npx",
      "args": ["-y", "@joemugen/obsidian-cli-mcp"],
      "env": {
        "MCP_PROFILE": "governed-readonly",
        "OBSIDIAN_BIN": "/opt/homebrew/bin/obsidian",
        "OBSIDIAN_VAULT": "MyVault",
        "OBSIDIAN_VAULT_ROOT": "/path/to/MyVault",
        "OBSIDIAN_POLICY_FILE": "/path/to/governed-vault-policy.json"
      }
    }
  }
}

泽德

编辑 ~/.config/zed/settings.json:

{
  "context_servers": {
    "obsidian-cli": {
      "command": {
        "path": "npx",
        "args": ["-y", "@joemugen/obsidian-cli-mcp"],
        "env": {
          "MCP_PROFILE": "governed-readonly",
          "OBSIDIAN_BIN": "/opt/homebrew/bin/obsidian",
          "OBSIDIAN_VAULT": "MyVault",
          "OBSIDIAN_VAULT_ROOT": "/path/to/MyVault",
          "OBSIDIAN_POLICY_FILE": "/path/to/governed-vault-policy.json"
        }
      }
    }
  }
}

HTTP传输（网络/多客户端）

MCP_PROFILE=governed-readonly MCP_TRANSPORT=http MCP_PORT=3000 \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_AUTH_TOKEN=change-me \
OBSIDIAN_BIN=/opt/homebrew/bin/obsidian \
OBSIDIAN_VAULT=MyVault \
OBSIDIAN_VAULT_ROOT=/path/to/MyVault \
OBSIDIAN_POLICY_FILE=/path/to/governed-vault-policy.json \
node dist/index.js

服务器在以下位置公开了一个可流式传输的HTTP端点 http://localhost:3000/mcp.

HTTP传输仍然是选择加入，不是默认部署路径。第2阶段硬化被故意限制：

  • 环回(127.0.0.1)保持默认绑定
  • 受控HTTP要求 MCP_HTTP_AUTH_TOKEN
  • 非环回绑定需要 MCP_HTTP_ALLOW_REMOTE_BIND=true
  • 没有显式opt-in的远程绑定失败关闭
  • 这是受控使用，而不是互联网安全部署模型

工具

默认值 governed-readonly 配置文件仅注册有界的受控读取和发现表面。 governed-mutation 添加了精确的路径注释/属性变异工具以及下面列出的受管工作流工具。完整的旧版工具目录仅在以下情况下可用 MCP_PROFILE=personal-unrestricted 已明确设置。

受控工作流工具

工具 说明
obsidian_search 仅在策略批准的发现根内使用服务器端结果过滤进行搜索
obsidian_search_context 在策略批准的发现根中使用有界上下文进行搜索
obsidian_list_links 列出允许注释中的传出链接，过滤服务器端被阻止的目标
obsidian_list_backlinks 列出允许注释的反向链接，在服务器端过滤被阻止的源
obsidian_create_note_from_template 将已批准的受管理模板类型中的注释创建到已批准的目标中
obsidian_create_review_note 为已批准的源注释创建来源保留审查注释
obsidian_create_promotion_candidate 为已批准的来源说明创建保存来源的晋升候选人说明
obsidian_create_curated_note 从批准的模板类型创建策划的笔记到批准的策划区域
obsidian_log_promotion 创建一个促销日志，将来源和策划的笔记链接起来

备注

工具 说明
obsidian_read_note 按名称或路径阅读笔记
obsidian_create_note 创建新笔记
obsidian_delete_note 删除注释
obsidian_move_note 将笔记移动到另一个文件夹
obsidian_rename_note 重命名笔记（更新所有反向链接）
obsidian_append_note 将内容附加到注释中
obsidian_prepend_note 将内容预先添加到注释中
obsidian_outline 获取笔记的标题大纲
obsidian_wordcount 获取单词和字符数
obsidian_file_info 获取文件元数据（路径、大小、日期…）
obsidian_diff 比较笔记的两个版本
obsidian_eval 在Obsidian上下文中执行JavaScript

金库

工具 说明
obsidian_vault_info 显示vault名称、路径和文件数
obsidian_list_files 列出文件，可选择按文件夹或扩展名筛选
obsidian_list_folders 列出所有文件夹
obsidian_list_vaults 列出所有黑曜石拱顶
obsidian_version 获取Obsidian和CLI版本
obsidian_list_recents 列出最近打开的文件
obsidian_random_read 从保险库或文件夹中读取随机笔记
obsidian_list_aliases 列出frontmatter中定义的所有注释别名

搜索

工具 说明
obsidian_search 在所有笔记中进行全文搜索
obsidian_search_context 使用周围环境进行搜索

前言

工具 说明
obsidian_list_properties 在注释中列出所有frontmatter属性
obsidian_get_property 获取特定的属性值
obsidian_set_property 设置属性值
obsidian_remove_property 删除属性

标签

工具 说明
obsidian_list_tags 列出vault或注释中的所有标记
obsidian_get_tag 获取使用特定标签的笔记

链接

工具 说明
obsidian_list_links 列出笔记中的传出链接
obsidian_list_backlinks 列出指向笔记的传入链接
obsidian_list_orphans 列出没有传入链接的笔记
obsidian_list_deadends 仅列出带有传出链接的笔记
obsidian_list_unresolved 列出损坏的维基链接

每日笔记

工具 说明
obsidian_read_daily 阅读今天的每日简报
obsidian_append_daily 将内容添加到今天的每日笔记中
obsidian_prepend_daily 为今天的每日笔记预置内容

任务

工具 说明
obsidian_list_tasks 在笔记或vault范围内列出任务
obsidian_toggle_task 切换任务复选框

模板

工具 说明
obsidian_list_templates 列出可用模板
obsidian_read_template 读取模板，可选择解析变量
obsidian_insert_template 在活动笔记中插入模板

书签

工具 说明
obsidian_list_bookmarks 列出所有书签（笔记、文件夹、搜索、URL）
obsidian_add_bookmark 添加书签

插件

工具 说明
obsidian_list_plugins 列出所有已安装的插件
obsidian_list_plugins_enabled 仅列出已启用的插件
obsidian_get_plugin 获取插件信息
obsidian_enable_plugin 启用插件
obsidian_disable_plugin 禁用插件
obsidian_install_plugin 安装社区插件
obsidian_uninstall_plugin 卸载插件

历史 （需要文件恢复插件）

工具 说明
obsidian_history_list 列出所有跟踪的版本
obsidian_history_read 阅读笔记的特定版本
obsidian_history_restore 将笔记还原到以前的版本

同步 （需要黑曜石同步）

工具 说明
obsidian_sync_status 获取当前同步状态
obsidian_sync_history 列出文件的同步版本
obsidian_sync_read 读取特定的同步版本
obsidian_sync_restore 将文件还原为同步版本
obsidian_sync_deleted 列出从同步历史记录中删除的文件

工作区

工具 说明
obsidian_workspace 获取当前工作区布局并打开窗格
obsidian_list_tabs 列出当前打开的所有选项卡
obsidian_daily_path 获取今天日记的文件路径

命令和热键

工具 说明
obsidian_list_commands 列出所有可用命令（命令选项板）
obsidian_execute_command 按ID执行黑曜石命令
obsidian_list_hotkeys 列出所有已配置的键盘快捷键
obsidian_get_hotkey 获取特定命令的热键

主题

工具 说明
obsidian_list_themes 列出所有已安装的主题
obsidian_get_theme 获取特定主题的信息
obsidian_set_theme 激活主题（或重置为默认值）
obsidian_install_theme 安装社区主题
obsidian_uninstall_theme 卸载主题

代码片段

工具 说明
obsidian_list_snippets 列出所有已安装的CSS代码段
obsidian_list_snippets_enabled 仅列出已启用的CSS代码段
obsidian_enable_snippet 启用CSS代码段
obsidian_disable_snippet 禁用CSS代码段

基础 （需要黑曜石基础插件）

工具 说明
obsidian_list_bases 列出所有基本文件
obsidian_query_base 从基础查询项目
obsidian_list_base_views 在Base中列出视图
obsidian_create_base_item 在Base中创建项目

贡献

看 贡献.md 了解架构概述、设计决策以及如何添加新工具。

许可证

看 许可证.

相关 MCP