适合谁
- 重度 Obsidian 用户希望 AI 代理直接读写自己的库
- 想要自托管、无插件、无外部 API 依赖的用户
- 需要从手机或远程访问库的移动/多设备工作流
- 关注数据安全的用户（OAuth 2.1、原子写入、容器加固）
V
79FMRS · B
Vault Cortex 是一个功能完整、工程质量较高的第三方 Obsidian MCP 服务器：混合搜索（FTS5 + 向量 + 重排序全部本地运行）、条目粒度的结构化记忆、看板感知的任务层、附件文件读取，以及完整的 OAuth 2.1 与数据完整性防护，在同类项目中少见。非官方（作者非 Obsidian 团队），但 MIT 许可、Docker 单容器部署门槛低，并有 CLI 向导。适合严肃使用 Obsidian 并愿意自托管的用户。
Vault Cortex 是一个独立的 MCP 服务器，为 AI 代理提供对 Obsidian 库的混合搜索、任务管理、结构化记忆和读写访问。无需插件、无需运行 Obsidian，一个 Docker 容器直接处理磁盘上的 .md 文件。可部署到 VPS 并配合 Obsidian Sync，实现手机、claude.ai 或任何远程 MCP 客户端访问，并以 OAuth 2.1 保护。搜索结合 FTS5 关键词匹配与向量语义相似度（RRF 融合），再由交叉编码器重排序；记忆层为带日期的只追加条目；任务层支持 Tasks 插件 emoji 与 Dataview 内联字段两种格式及看板泳道操作；文件工具可读取图片、Canvas、PDF、CSV 等非 Markdown 文件。传输方式为 streamable-http（http://localhost:8000/mcp 或 <PUBLIC_URL>/mcp）。
工具能力
vault_read_note
读取笔记——正文全文、属性、大纲或指定章节
vault_write_note
创建笔记（已存在则失败，可设置 overwrite 覆盖）
vault_patch_note
针对标题的编辑（追加、前插、替换、插入）
vault_replace_in_note
在笔记中查找并替换文本
vault_delete_span
按短锚点删除行块，无需完整重引
vault_list_notes
列出笔记，支持 glob/文件夹过滤
vault_delete_note
删除笔记（受保护路径强制生效）
vault_move_note
移动或重命名笔记，并重写全库链接
vault_search
混合搜索，支持标签/文件夹/属性/日期过滤
vault_search_by_tag
按标签查找笔记（精确或前缀匹配）
vault_search_by_folder
按文件夹浏览笔记并带元数据
vault_recent_notes
最近修改或创建的笔记
vault_list_tags
所有标签及使用次数
vault_list_tasks
全库任务索引——看板感知，6 个日期字段、优先级、文件夹/标题范围
vault_update_task
单次调用完成状态、优先级和泳道变更——自动检测看板完成泳道
vault_get_memory
读取结构化记忆（文件、章节或全部）
vault_update_memory
向记忆章节追加带日期的条目
vault_delete_memory
按日期移除特定记忆条目
vault_list_memory_files
发现记忆文件、章节及各文件的条目策略
vault_memory_recall
跨记忆文件对主题进行条目粒度的混合召回，最旧优先
vault_list_property_keys
所有属性键及示例值
vault_list_property_values
某属性键的去重取值
vault_search_by_property
按属性键值查找笔记
vault_update_properties
添加或更新属性而不改动正文
vault_get_backlinks
链接到指定路径的笔记
vault_get_outgoing_links
指定笔记的出链
vault_find_orphans
无入链的孤立笔记
vault_read_file
读取非 Markdown 文件——图片以图片交付，Canvas 转为可读大纲
vault_list_files
浏览库中非 Markdown 文件，含大小与扩展名统计
vault_get_daily_note
今天（或任意日期）的日记笔记
安装接入
需 Docker（或 Podman、OrbStack 等兼容运行时）；CLI 需 Node.js >= 20.12。本地快速开始：运行 npx vault-cortex@latest init，交互向导会询问库路径、生成令牌和配置并启动服务器；服务器地址 http://localhost:8000/mcp。远程部署：在 VPS 上运行 npx vault-cortex@latest init --mode remote，配合 Obsidian Sync 订阅。也可用 docker compose 手动部署（镜像 ghcr.io/aliasunder/vault-cortex）。连接 Claude Code：claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp。
选型与风险
不适合谁
- 不想使用 Docker 或自托管服务器的用户
- 非 Obsidian 的笔记工具（如 Notion、Logseq）用户
- 只想要 stdio 本地进程、无需 HTTP 服务器的场景
- 无 Obsidian Sync 订阅的远程多设备同步需求（远程镜像需要订阅）
所需权限
- 对 Obsidian 库文件夹的读写访问（bind mount /vault，rw）
- 持久化数据卷 /data（搜索索引、OAuth 令牌数据库、日志）
- MCP_AUTH_TOKEN 作为 Bearer 令牌（也是 JWT 签名密钥）
- 远程模式下需要 Obsidian Sync 令牌进行无头同步
- 本地下载数字/嵌入/重排序模型（约 45MB），无外部 API 调用
风险与副作用
- 服务器可读写个人笔记——必须妥善保管 MCP_AUTH_TOKEN，泄露即等于泄露整个库
- 写入真实笔记文件，虽有原子写入与受保护路径，配置错误仍可能改动数据
- OAuth 令牌数据库存于 /data 卷，容器被入侵可能暴露有效会话
- 远程部署暴露公网端口，需正确设置 PUBLIC_URL 与反向代理
- 远程镜像捆绑专有的 obsidian-headless（非 MIT 许可），需有效的 Obsidian Sync 订阅
常见排障
- 401 错误：确认客户端 Authorization 头与容器 MCP_AUTH_TOKEN 一致
- Windows 上文件变更未被索引：设置 WINDOWS_MODE=true 启用轮询监视
- 本地 localhost 无法在 claude.ai 使用：claude.ai 连接器只能访问远程（https）部署
- Claude Desktop 本地连接：需通过 mcp-remote stdio 桥接配置
- 搜索结果不含语义匹配：检查 EMBEDDING_ENABLED 是否为 true
- 内存不足或模型下载失败：语义搜索约需 2GiB 内存，可设 EMBEDDING_ENABLED=false 回退到 FTS5
使用场景
从手机或远程客户端搜索并回顾个人知识库内容
让 AI 代理读取会话笔记、总结经验并写回库中
全库任务分诊：按状态、日期、优先级查询并一键完成或改优先级
维护带日期演化的个人偏好与原则记忆层
分析笔记间的链接图谱、查找孤立笔记
让代理读取库内截图、架构图 PDF、Canvas 等附件
支持客户端
Claude Code完整支持
Claude Desktop完整支持
claude.ai部分支持
Cursor部分支持
OpenCode完整支持
MCP Inspector完整支持