Vault Cortex MCP Server

社区

独立的 Obsidian 库 MCP 服务器：混合搜索、笔记与文件、结构化记忆、任务管理，支持 OAuth 2.1。

分类: 文件系统第 2 / 24
Stars: ★ 30 热门
传输方式: Streamable HTTP
运行环境: Docker · Node.js 20.12+
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 5 天前
工具数: 30

79FMRS · B

Vault Cortex 是一个功能完整、工程质量较高的第三方 Obsidian MCP 服务器：混合搜索（FTS5 + 向量 + 重排序全部本地运行）、条目粒度的结构化记忆、看板感知的任务层、附件文件读取，以及完整的 OAuth 2.1 与数据完整性防护，在同类项目中少见。非官方（作者非 Obsidian 团队），但 MIT 许可、Docker 单容器部署门槛低，并有 CLI 向导。适合严肃使用 Obsidian 并愿意自托管的用户。

最强项 · 文档质量 19/20 最弱项 · 可靠性 12/20

可靠性

12/20

安全与权限

18/20

维护活跃度

15/20

文档质量

19/20

安装易用性

15/20

查看各项评分依据

可靠性 12/20: 项目提供了完整的Docker容器化部署方案，包含清晰的启动流程和配置选项。从README可以看出，项目有CI/CD流程、测试覆盖和版本管理。但作为静态代码审查，无法验证实际运行时表现和错误处理能力。项目版本0.49.0显示有一定成熟度，但无法确认所有工具在实际使用中的稳定性。
安全与权限 18/20: 项目实现了OAuth 2.1认证机制，包含PKCE和刷新令牌轮换，这在MCP服务器中较为先进。有明确的路径遍历防护、原子写入和并发控制机制。代码中包含安全检查和输入验证。项目明确标识了敏感信息处理方式，如MCP_AUTH_TOKEN。但作为静态审查，无法验证所有安全措施的实际有效性。
维护活跃度 15/20: 项目显示活跃的开发状态，有明确的版本号(0.49.0)、CI/CD流程和依赖管理。项目使用MIT许可证，开源且允许商业使用。有贡献指南和明确的开发流程。GitHub上有15个星标和2个开放问题，表明有一定社区参与度。但项目规模相对较小，长期维护的可持续性有待观察。
文档质量 19/20: 文档非常全面，包含详细的安装指南、配置选项、工具说明和使用示例。README结构清晰，包含了快速入门、功能介绍、架构说明和故障排除信息。提供了详细的配置参数说明和默认值。有专门的架构文档(ARCHITECTURE.md)和安全文档(SECURITY.md)。文档覆盖了本地和远程部署场景，并提供了多种客户端连接方式。
安装易用性 15/20: 项目提供了多种部署方式，包括本地Docker、远程部署和AWS部署。有详细的初始化脚本和配置生成工具。支持Docker Compose和手动部署两种方式。提供了针对不同操作系统(包括Windows)的特定说明。但部署过程需要一定的技术背景，特别是远程部署需要配置VPS和Obsidian Sync。

静态评测 · 未实际运行收录于 2026-09-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件

适合谁

重度 Obsidian 用户希望 AI 代理直接读写自己的库
想要自托管、无插件、无外部 API 依赖的用户
需要从手机或远程访问库的移动/多设备工作流
关注数据安全的用户（OAuth 2.1、原子写入、容器加固）

不适合谁

不想使用 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 订阅

安装接入

准备工作

运行环境：Docker · Node.js 20.12+

MCP_AUTH_TOKEN 必填密钥 MCP 客户端认证的 Bearer 令牌，可用 `openssl rand -hex 32` 生成，为必需项。

VAULT_PATH 必填宿主机上 Obsidian vault 的绝对路径，本地部署必需。

OBSIDIAN_AUTH_TOKEN 可选密钥远程部署时用于 Obsidian Sync 的令牌，可通过 CLI `get-sync-token` 获取。

其他可选配置项（23 个）

PUBLIC_URL 可选客户端访问服务器的公网 URL，作为 OAuth issuer，仅在远程部署时设置。

EMBEDDING_ENABLED 可选是否启用嵌入向量管线；设为 false 时仅用 FTS5 关键词搜索。

RERANK_MODE 可选交叉编码器重排模式：blended 或 none。

WINDOWS_MODE 可选

MEMORY_ENABLED 可选

FILE_TOOLS_ENABLED 可选

READONLY_MODE 可选设为 true 时隐藏所有写入类工具，服务器只读运行。

DISABLED_TOOLS 可选

MEMORY_DIR 可选

DAILY_NOTES_FOLDER 可选

DAILY_NOTES_FORMAT 可选

TRUST_PROXY_HOPS 可选

TRUST_FORWARDED_HOPS 可选

TZ 可选

LOG_LEVEL 可选

LOG_DIR 可选

LOG_RETENTION_DAYS 可选

PROTECTED_PATHS 可选

ORPHAN_EXCLUDE_FOLDERS 可选

SERVICE_DOCUMENTATION_URL 可选

MAX_FILE_BYTES 可选

MAX_IMAGE_OUTPUT_BYTES 可选

MAX_PDF_RENDER_PAGES 可选

需 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。

验证是否装好

运行 `npx vault-cortex@latest init` 启动服务器后，在 MCP 客户端（如 Claude Code）中添加 `http://localhost:8000/mcp`，确认工具列表中出现 `vault_search` 和 `vault_read_note`；然后问“我库里有哪些最近修改的笔记？”来验证连接。

常见排障

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 助手这样说：

搜索我的知识库中关于混合搜索架构的笔记，并总结要点。
把今天学到的一条经验追加到我的记忆文件里。
列出所有状态为待办且已过截止日期的任务。
帮我读取仓库里那张 5MB 的架构图并解释内容。

工具能力 30

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 写入

移动或重命名笔记，并重写全库链接

展开其余 22 个工具

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 只读

今天（或任意日期）的日记笔记

使用场景

从手机或远程客户端搜索并回顾个人知识库内容

让 AI 代理读取会话笔记、总结经验并写回库中

全库任务分诊：按状态、日期、优先级查询并一键完成或改优先级

维护带日期演化的个人偏好与原则记忆层

分析笔记间的链接图谱、查找孤立笔记

让代理读取库内截图、架构图 PDF、Canvas 等附件

支持客户端

Claude Code

Claude Desktop

Claude.ai部分支持

Cursor部分支持

OpenCode

MCP Inspector

依据项目文档列出，未经本站实测。

详细介绍

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）。