Obsidian Vault MCP

保险库作为MCP

一个黑曜石插件，运行MCP（模型上下文协议）服务器，使外部LLM工具能够访问您的保管库。本机支持HTTP传输（Open WebUI、远程LLM），并通过附带的桥接脚本（Claude Desktop）支持stdio传输。

重要说明 - 网络使用：此插件在您的计算机上运行本地HTTP服务器。它不连接到外部服务。 - 隐私：无遥测或数据收集。所有数据都保留在您的机器上。 - 仅限桌面：此插件需要桌面环境，无法在移动设备上运行。

特性

• 基于HTTP的MCP服务器：运行实现MCP协议的Fastify服务器
• 状态栏指示器：通过单击切换功能显示服务器状态（已停止/正在运行/错误）
• 可配置设置：调整服务器端口、自动启动行为和日志级别
• CORS支持：允许通过Tailscale或本地网络从远程计算机进行访问
• MCP工具:

- read_note -按路径读取笔记内容；可选择扩展嵌入式内容 - read_multiple_notes -在一个请求中阅读多个笔记 - search_notes -按文件夹、标签、封面、文本或近距查找笔记 - get_linked_notes -从笔记中获取传出链接 - list_notes -在目录中列出笔记和子文件夹 - create_note -从模板或直接内容创建笔记 - append_to_note -将内容附加到现有注释中 - update_note -通过替换整个内容来更新现有注释 - delete_note -删除笔记（移至系统垃圾箱） - rename_note -重命名或移动注释，更新所有vault链接 - get_current_date -获取基于日期的操作的当前日期 - read_periodic_note -获取定期笔记（每日/每周/每月/每季度/每年）的路径和内容（如果存在） - list_templates -列出可用的模板和模板插件

安装

手动安装

1. 从GitHub下载最新版本
2. 将文件提取到vault .obsidian/plugins/vault-as-mcp/ 目录
3. 重新加载黑曜石
4. 在设置中启用“Vault as MCP”→ 社区插件

使用BRAT进行安装

假设您已安装并启用BRAT插件：

1. 打开BRAT插件设置
2. 点击“添加测试版插件”
3. 使用 https://github.com/ebullient/obsidian-vault-mcp 作为URL，选择最新版本并安装
4. 启用“Vault as MCP”，可以作为通过BRAT安装的一部分，也可以在设置中启用→ 社区插件

用法

启动服务器

该插件提供了三种控制服务器的方法：

1. 状态栏：单击右下角的状态指示器以打开/关闭服务器
2. 命令：使用命令选项板可以：

- 启动MCP服务器 - 停止MCP服务器 - 重新启动MCP服务器

1. 自动启动：在设置中启用，以便在加载黑曜石时自动启动服务器

配置

打开设置→ 保险库作为MCP：

• 服务器端口：MCP服务器的端口号（默认值：8765）
• 持有者令牌：用于安全访问的可选身份验证令牌
• 自动启动服务器：加载黑曜石时自动启动
• 调试：启用调试消息

认证

承载令牌身份验证是可选的，但建议出于安全考虑，特别是在通过网络访问您的保管库时。

要启用身份验证，请执行以下操作：

1. 打开设置→ 保险库作为MCP
2. 点击“生成”以创建安全的随机令牌（或输入您自己的令牌）
3. 复制令牌以在客户端配置中使用
4. 保存设置并重新启动服务器（如果正在运行）

要禁用身份验证，请执行以下操作：

1. 打开设置→ 保险库作为MCP
2. 单击“清除”删除令牌
3. 保存设置并重新启动服务器（如果正在运行）

从Open WebUI连接

在Open WebUI的MCP配置中，添加一个新服务器： http://localhost:8765/mcp

如果Open WebUI正在远程计算机上运行（例如，通过Tailscale）： http://:8765/mcp

启用身份验证，使用以下命令从Open WebUI中的MCP服务器配置中添加承载令牌 Authorization 头球

Authorization: Bearer 

与克劳德代码连接

claude mcp add -t http -s local Obsidian http://localhost:8765/mcp -H "Authorization: Bearer "

笔记：

• 确保您的端口与插件设置中配置的端口匹配
• 启用身份验证并使用插件设置中的承载令牌

克劳德桌面版

Claude Desktop为MCP服务器使用stdio传输，因此您需要 mcp-bridge.js 用于将stdio桥接到HTTP的脚本。

要求：

• Node.js 18+（用于本机获取支持）
• “Vault as MCP”插件已启用，服务器在Obsidian中运行

设置stdio网桥（替代http）：

1. 下载 mcp-bridge.js 从

并将其保存在可访问的地方（例如。， ~/.obsidian/scripts/mcp-bridge.js)

1. 查找您的Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/claude/claude_desktop_config.json

1. 添加MCP服务器配置：

   {
     "mcpServers": {
       "obsidian-vault": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-bridge.js"],
         "env": {
           "VAULT_MCP_URL": "http://localhost:8765/mcp"
         }
       }
     }
   }

启用身份验证，添加 VAULT_MCP_TOKEN 环境 变量：

   {
     "mcpServers": {
       "obsidian-vault": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-bridge.js"],
         "env": {
           "VAULT_MCP_URL": "http://localhost:8765/mcp",
           "VAULT_MCP_TOKEN": "your-token-here"
         }
       }
     }
   }

1. 重要：替换 /absolute/path/to/mcp-bridge.js 与实际

保存桥脚本的路径

1. 重新启动克劳德桌面

测试：

• 桥会记录到stderr，因此您可以在Claude Desktop的日志中看到它的活动
• 在Claude中，您应该看到vault的MCP工具可用
• 试着让克劳德“在路径Daily Notes/today.md上阅读我的笔记”

故障排除：

• 验证插件服务器是否正在运行（检查黑曜石状态栏）
• 检查路径 mcp-bridge.js 是正确和绝对的
• 确保已安装Node.js 18+： node --version
• 在Claude Desktop的日志中查找网桥错误

MCP工具参考

read_note

按路径阅读笔记内容。默认情况下返回原始markdown。通过 includeEmbeds: true 仅 当明确请求嵌入内容时，嵌入扩展是昂贵的。

参数：

• path （string，必填）：指向注释的路径（例如。， "folder/note.md")
• sections （string\[\]，可选）：仅通过标题文本返回这些部分（不区分大小写，包括副标题）
• includeEmbeds （布尔值，可选）：展开 ![[embed]] 内联块（最多2层深）。违约： false
• includeLinks （boolean，可选）：也展开常规 [[links]] 内联。仅在以下情况下相关 includeEmbeds 是 true默认值： false
• excludePatterns （string\[\]，可选）：跳过某些嵌入的正则表达式模式。仅在以下情况下相关 includeEmbeds 是 true

示例（平读）：

{
  "name": "read_note",
  "arguments": {
    "path": "Daily Notes/2025-01-15.md"
  }
}

示例（扩展了嵌入式内容）：

{
  "name": "read_note",
  "arguments": {
    "path": "Projects/overview.md",
    "includeEmbeds": true
  }
}

search_notes

按文件夹、标记、封面、修改时间或文本内容在vault中查找注释。 所有参数都是可选的，并与and逻辑结合使用，除了 tags[] 其中OR在 标签尺寸。使用 list_notes 当文件夹结构（子文件夹名称）很重要时。

参数：

• folder （字符串，可选）：仅限于此文件夹路径下的笔记（递归）
• tag （字符串，可选）：单标记过滤器，与AND逻辑和其他参数结合使用
• tags （string\[\]，可选）：返回具有这些标签（或逻辑）中的任何一个的注释；不能与 tag
• text （字符串，可选）：单词必须全部出现（任何顺序）；引用短语： meeting "action items"
• mtime （对象，可选）：按修改时间过滤-- before 和 after；每个都接受一个ISO日期("2026-04-25")或相对天数("7d" =7天前）
• frontmatter （对象，可选）：按前体键/值过滤，例如。 {"type": "quest"}
• sort （字符串，可选）： "alpha" （默认）或 "recent" （最新修改在先）
• limit （数字，可选）：最大结果；仅在以下情况下适用 sort 是 "recent" （默认值：20，最大值：50）

示例（标签+文件夹AND过滤器）：

{
  "name": "search_notes",
  "arguments": {
    "tag": "project",
    "folder": "quests"
  }
}

示例（跨多个标签的OR）：

{
  "name": "search_notes",
  "arguments": {
    "tags": ["tech/ai", "tech/mcp"]
  }
}

示例（最近修改）：

{
  "name": "search_notes",
  "arguments": {
    "folder": "chronicles",
    "sort": "recent",
    "limit": 10
  }
}

get_linkd_notes

获取从特定笔记链接的所有笔记（传出链接）。

参数：

• path （string，必填）：注释路径

例子：

{
  "name": "get_linked_notes",
  "arguments": {
    "path": "Projects/Main.md"
  }
}

create_note

创建一个新的笔记或二进制文件。可以从模板或直接内容创建。如果需要，自动创建父文件夹。

参数：

• path （string，必填）：新文件的路径（例如。， "folder/note.md" 或 "assets/diagram.png").这 .md 文本注释会自动添加扩展名。
• content （string，可选）：文件内容。对于文本注释，这是markdown。对于二进制文件，这必须是base64编码的数据。如果满足以下条件，则不需要 template 已指定。
• template （string，可选）：模板文件的路径（例如。， "templates/daily.md").需要核心模板或Templater插件。如果指定， content 被忽略。
• binary （布尔值，可选）：设置为 true 用于二进制文件（图像、PDF）。违约： false.

示例（文本注释）：

{
  "name": "create_note",
  "arguments": {
    "path": "Projects/new-idea.md",
    "content": "# New Idea\n\nThis is my new note content."
  }
}

示例（二进制文件）：

{
  "name": "create_note",
  "arguments": {
    "path": "assets/diagram.png",
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "binary": true
  }
}

示例（来自模板）：

{
  "name": "create_note",
  "arguments": {
    "path": "Daily Notes/2025-01-19.md",
    "template": "templates/daily.md"
  }
}

笔记：

• 如果文件已存在，则失败并出现错误
• 父文件夹是自动创建的
• 返回创建文件的路径
• 二进制文件支持：通过base64编码的PNG、JPG、PDF和其他格式
• 模板支持需要Templater或核心模板插件
• Templater提供完整的模板处理（日期、提示、动态内容）
• 核心模板处理基本日期变量和模板内容

附录_注释

将内容附加到现有注释中。可以附加到文件末尾或特定标题之后。

参数：

• path （string，必填）：指向注释的路径（例如。， "folder/note.md")
• content （string，必填）：要附加的内容
• heading （string，可选）：要在后面附加的标题（例如。， "## Tasks").如果未指定，则附加到文件末尾。
• separator （字符串，可选）：现有内容和新内容之间的分隔符。违约： "\n" （单行）

示例（附加到文件末尾）：

{
  "name": "append_to_note",
  "arguments": {
    "path": "Daily Notes/2025-01-18.md",
    "content": "## Meeting Notes\n\n- Discussed project timeline"
  }
}

示例（在标题后附加）：

{
  "name": "append_to_note",
  "arguments": {
    "path": "Projects/roadmap.md",
    "content": "- [ ] Implement new feature",
    "heading": "## Q1 Tasks"
  }
}

自定义分隔符示例：

{
  "name": "append_to_note",
  "arguments": {
    "path": "Projects/tasks.md",
    "content": "- [ ] New task",
    "separator": "\n\n"
  }
}

笔记：

• 如果注释不存在，则失败并出现错误
• 如果找不到指定的标题，则失败并出现错误
• 标题必须完全匹配（包括 ## 标记）
• 内容附在标题部分的末尾
• 使用 create_note 首先，如果注释可能不存在
• 返回笔记的路径

update_note

通过替换其全部内容来更新现有注释。当您需要对笔记进行大量更改时，这很有用。

参数：

• path （string，必填）：指向注释的路径（例如。， "folder/note.md")
• content （string，必填）：将替换整个文件的新内容

例子：

{
  "name": "update_note",
  "arguments": {
    "path": "Projects/roadmap.md",
    "content": "# Updated Roadmap\n\n## Q1 2025\n\n- [x] Feature A\n- [ ] Feature B"
  }
}

笔记：

• 如果注释不存在，则失败并出现错误
• 替换整个文件内容（而不是部分更新）
• 典型工作流程：使用 read_note 首先，修改内容，然后 update_note
• 返回笔记的路径

delete_note

通过将笔记移至系统回收站来删除它。这比永久删除更安全，因为文件可以恢复。

参数：

• path （string，必填）：要删除的笔记的路径（例如。， "folder/note.md")

例子：

{
  "name": "delete_note",
  "arguments": {
    "path": "Archive/old-note.md"
  }
}

笔记：

• 如果注释不存在，则失败并出现错误
• 文件已移动到系统垃圾箱（未永久删除）
• 如果文件被错误删除，可以从垃圾箱中恢复
• 返回已删除笔记的路径

read_periodic_note

根据配置的设置获取定期票据的文件路径，如果文件存在，则返回其内容。支持每日、每周、每月、每季度和每年的笔记。首先检查定期笔记插件，然后退回到每日笔记的核心每日笔记插件。

参数：

• period （字符串，必填）：句点类型-以下之一： "daily", "weekly", "monthly", "quarterly", "yearly"
• date （字符串，可选）：ISO格式的日期（例如。， "2025-01-18").默认为当前日期。

退货： path 总是； content 仅当笔记文件存在时。

示例（每日笔记）：

{
  "name": "read_periodic_note",
  "arguments": {
    "period": "daily",
    "date": "2025-01-18"
  }
}

示例（本周的周报）：

{
  "name": "read_periodic_note",
  "arguments": {
    "period": "weekly"
  }
}

示例（月报）：

{
  "name": "read_periodic_note",
  "arguments": {
    "period": "monthly",
    "date": "2025-01-01"
  }
}

笔记：

• 对于非每日时段（每周、每月、每季度、每年），需要安装和配置Periodic Notes社区插件
• 对于每日笔记，如果定期笔记不可用，则退回到核心每日笔记插件
• 根据用户在插件中配置的格式和文件夹设置返回路径
• 如果未安装所需的插件或未启用时段类型，则失败
• 路径格式取决于用户的设置（例如。， "Daily Notes/2025-01-18.md" 或 "Weekly/2025-W03.md")
• 如果笔记文件尚不存在，则仅 path 返回（否 content 现场）

list_templates

列出可用的笔记模板以及启用了哪些模板插件。有助于在创建笔记之前发现现有的模板。

参数：

无

例子：

{
  "name": "list_templates",
  "arguments": {}
}

退货：

{
  "templates_folder": "templates",
  "templates": [
    "templates/daily.md",
    "templates/meeting.md",
    "templates/project.md"
  ],
  "core_templates_enabled": true,
  "templater_enabled": true
}

笔记：

• 返回已配置的模板文件夹路径
• 列出所有 .md templates文件夹中的文件（递归）
• 指示启用了哪些模板插件（核心模板、Templater）
• 模板文件夹位置来自插件设置
• 如果两个插件都未启用， templates 数组仍将列出默认模板文件夹中的文件

发展

看 贡献.md 用于开发设置、构建命令和架构细节。人工智能助手也应该进行审查 CLAUDE.md 工作指南。

许可证

麻省理工学院

作者

兴高采烈的