obsidian-mcp 是一个自托管的 Model Context Protocol（MCP）服务器，旨在为 AI 智能体提供持久、共享且人类可审计的记忆系统。其核心存储并非不可见的向量数据库，而是用户 Obsidian 库中的纯 Markdown 文件，并辅以全文搜索、语义搜索和 wikilink 图谱。Obsidian 作为人类查看窗口，用户可以打开笔记、阅读智能体写入的内容、进行修正或删除，也可以将整个文件夹迁移到别处。
用途
该服务器为连接的 MCP 客户端提供可访问的存储、关键词与语义搜索，以及针对 Markdown 笔记的图谱操作。智能体自主决定读写内容，服务器本身不运行自动提取、整合或衰减管道——智能体通过写入笔记来记住信息，通过删除笔记来遗忘信息。
主要能力
服务器暴露 25 个 MCP 工具，分为五类：
搜索与发现：keyword_search（基于 PostgreSQL tsvector 的全文搜索，支持文件夹、标签、frontmatter 过滤）、semantic_search（基于 pgvector 的向量相似度搜索，每篇笔记返回一个预览块）、list_notes（按修改时间排序）、get_recent（最近更改）、get_tags（标签及计数）、get_vault_guide（实时提供 Obsidian 入门指南及该库的 CLAUDE.md）。
笔记读写：read_note 返回结构化结果（路径、标题、标签、frontmatter YAML 及 JSON 视图、标题、内容、截断信息等），支持按 section 读取单个章节或通过 offset 继续截断读取，受 MAX_READ_RESPONSE_CHARS（默认 40,000）限制。create_note 原子写入，拒绝覆盖。edit_note 支持四种互斥模式：完全替换（默认）、追加（append=True）、查找替换（find=…，可选 replace_all）、按章节编辑（section=<heading>，支持 ATX 标题、Parent/Child 路径风格及 #N 序号消歧），dry_run=True 返回统一 diff 而不写入。move_note 移动笔记并可选择重写传入的 wikilink 引用（[[Old]]、[[Old|alias]]、[[Old#anchor]]、![[Old]]、[[folder/Old]]）。delete_note 默认软删除到 .trash/ 目录（带时间戳和哈希，单次非替换重命名，避免覆盖已有回收站条目），permanent=True 则永久删除。set_frontmatter 进行结构化 YAML 变更，仅修改 frontmatter 时正文保持字节一致。
文件访问（非 Markdown）：read_file、write_file、list_files、delete_file 用于任意库文件（PDF、图片、技能资产、数据文件）的原始读写与浏览。纯字节传输，无服务端 PDF/文本提取，也不对非 Markdown 文件进行嵌入或索引。read_file 对文本类文件返回文本，图片返回内联图像块，其他二进制返回 base64 字符串；受 MAX_FILE_READ_BYTES（默认 10 MB）和 MAX_READ_RESPONSE_CHARS 限制，可通过 offset 继续。write_file 默认不覆盖，自动创建父目录，原子写入，上限 MAX_FILE_WRITE_BYTES（默认 25 MB）。list_files 提供 ls 风格浏览，支持 glob 过滤和结果上限。delete_file 软删除非 Markdown 文件到 .trash/，拒绝 Markdown（应使用 delete_note）、目录和符号链接。所有文件工具复用路径遍历防护，并排除任何以点开头的路径组件（如 .obsidian、.git、.trash）。
编辑防护：编辑、更新 frontmatter、移动或删除笔记、覆盖或删除原始文件时，可传入读取时获得的 content_hash 作为 expected_hash。规范令牌为 sha256:<64 位小写十六进制>，基于完整原始文件字节计算。过期的令牌会在变更前拒绝操作，并返回包含 stale_precondition 和当前哈希的 MCP-REFUSAL JSON 行。该参数默认可选，WRITE_PRECONDITION_REQUIRED=true 可强制要求。创建操作豁免，且拒绝提供的令牌（no_incumbent）。超过读取上限的文件无法被防护。
传输能力：由于 MCP 客户端无法直接传递用户正在查看的文件字节，服务器提供短时能力链接，通过公共 /transfer/* 路由兑换。request_upload 生成绑定单一目标路径的一次性链接，用户打开后选择文件即落盘到指定路径。check_upload 报告 pending/uploading/completed/unknown/revoked/expired 状态。request_download 生成下载链接。
使用方式
服务器基于 Python 3.12、FastAPI、PostgreSQL 与 pgvector 构建，嵌入模型可插拔（Ollama bge-m3 或 OpenAI text-embedding-3-small/large）。支持 OAuth 或 bearer key 认证，可多用户模式运行。智能体通过 MCP 协议连接后，可自主调用上述工具进行读写。库具有自描述性：智能体在首次调用时即可读取库指南，了解文件夹布局、frontmatter 模式和标签约定，无需每次会话重新说明。
适用场景
适用于希望为 AI 智能体提供持久、可审计记忆的用户，尤其是已使用 Obsidian 管理笔记的人群。典型场景包括：家庭实验室配置管理（智能体查找并修改配置，同时更新文档）、跨会话项目笔记更新（如从 Claude Code 会话生成 Obsidian 会话日志）、移动端与智能体对话时访问同一库（通过 OAuth 保护，可从浏览器、手机、n8n 工作流或任意笔记本访问）。
限制
服务器不提供自动提取、整合或衰减管道；记忆完全依赖智能体主动写入和删除。非 Markdown 文件仅作字节传输，不进行文本提取、嵌入或索引。文件读写有大小上限（默认读取 10 MB、写入 25 MB），笔记读取响应有字符上限（默认 40,000）。路径遍历防护排除所有点开头的路径组件。超过读取上限的文件无法使用哈希防护。具体安装命令、配置细节及完整 API 参数请参考项目仓库。
