Obsidian MCP Server

对于 Obsidian 用户来说，知识库就是第二个大脑。我们在其中精心构建笔记网络、维护知识图谱，但当与 AI 助手协作时，这座宝库却常常被隔绝在外——AI 无法直接读取你的笔记、搜索你的想法或是帮你整理知识结构。Obsidian MCP Server 彻底打破了这堵墙。它通过模型上下文协议（MCP），让你的 AI 助手能够直接与 Obsidian 知识库交互，实现安全的文件操作、内容管理和智能搜索，真正将 AI 变成知识管理的伙伴。

项目基本信息

一、项目介绍

Obsidian MCP Server 是一个用 TypeScript 构建的 MCP 服务器，它作为桥梁，将 Obsidian 本地知识库的强大管理能力以标准化的 MCP 工具形式暴露给 AI 客户端（如 Claude Desktop）。其核心设计理念是安全、高效、可扩展。

核心能力概览

项目提供了三大类工具，覆盖知识库管理的核心需求：

• 文件操作：支持原子化的文件和目录操作，包括列出文件、读取内容、追加内容、覆盖更新等。所有操作都内置了内容验证和错误处理机制。
• 搜索系统：提供两种搜索模式。obsidian_find_in_file 支持全文搜索，可配置返回匹配词的上下文长度；obsidian_complex_search 使用 JsonLogic 查询和 glob 模式对文件路径进行精确匹配。
• 属性管理：支持读取和更新笔记的 YAML frontmatter 属性。可以智能合并标签、状态等数组属性，或选择完全替换，还能自动管理时间戳字段。

此外，服务器还内置了安全与性能保障机制：API 密钥认证、速率限制、请求超时控制，以及对自签名证书的 SSL 选项支持。

与 Obsidian 的通信方式

该服务器并不直接操作文件系统，而是通过 Obsidian 的 Local REST API 插件 进行通信。这意味着所有操作都在 Obsidian 的运行环境中执行，遵循其缓存和索引机制，更加安全可靠。

二、核心优势

安全至上的设计

与直接操作 Markdown 文件相比，通过 Local REST API 插件交互具有显著的安全优势。所有请求都需要 API 密钥认证，服务器内置了速率限制和请求大小控制，避免了意外的大规模文件修改或恶意访问。

丰富的搜索能力

obsidian_complex_search 引入了 JsonLogic 查询语言，能够构建复杂的逻辑过滤条件。结合 obsidian_find_in_file 的全文检索和上下文提取功能，你可以实现精准的知识发现，而不仅仅是简单关键词匹配。

灵活的属性管理

对 YAML frontmatter 的操作不仅仅是读写，而是实现了智能合并和可选替换。更新标签时，默认行为是追加而非覆盖，这更符合笔记属性管理的实际需求。自动时间戳管理让笔记的修改历史更加清晰。

高度可配置

通过丰富的环境变量，你可以精细控制服务器的各项行为：API 协议、主机地址、端口、超时时间、速率限制窗口等，适应不同的本地网络环境。

Apache 2.0 开源协议

采用对商业使用友好的 Apache 2.0 协议，可以自由集成到个人或商业工作流中。

三、适用场景

智能笔记查询与回顾

你可以让 AI 助手直接在 Obsidian 中搜索信息：“在我的知识库里搜索关于'MCP协议'的笔记，找出所有提到'安全性'的部分，并总结要点。”AI 会使用全文搜索工具找到相关笔记并提炼内容。

自动化笔记整理

让 AI 帮助你维护知识库结构：“列出'Projects'文件夹下的所有笔记，根据它们的标签自动生成一个索引文件。”

写作辅助与内容扩展

在撰写笔记时，让 AI 直接读取你的历史笔记作为参考：“我正在写关于'认知负荷'的笔记，帮我在知识库里找找之前有没有相关的记录，有的话把关键观点引用过来。”

知识图谱属性批处理

批量更新笔记元数据：“把所有标签为'draft'的笔记，将其状态更新为'ready-to-review'，并添加今天的日期到'updated'字段。”

四、安装教程

环境要求

前置步骤：配置 Obsidian

1. 打开 Obsidian，进入 设置 -> 社区插件 -> 浏览。
2. 搜索 "Local REST API" 并安装。
3. 启用插件后，进入其设置，生成一个 API 密钥并妥善保存。

安装服务器

方式一：克隆并构建（推荐）

git clone git@github.com:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build

方式二：通过 npm 安装

# 本地安装
npm install obsidian-mcp-server

# 或全局安装
npm install -g obsidian-mcp-server

配置 MCP 客户端

编辑你的 MCP 客户端配置文件（以 Claude Desktop 为例）：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置，务必替换路径和 API 密钥：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "你的_api_密钥",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

关键环境变量说明：

• OBSIDIAN_API_KEY：必填，来自 Local REST API 插件设置。
• VERIFY_SSL：本地使用时建议设为 "false"。
• OBSIDIAN_PROTOCOL：通常为 "https"，如果 REST API 配置为 HTTP 则对应修改。

保存配置文件后，完全退出并重启 MCP 客户端，连接即生效。

五、使用示例

示例一：搜索笔记内容

用户：在我的 Obsidian 知识库中搜索关于“认知偏差”的笔记，把找到的要点列出来。

AI 调用 obsidian_find_in_file 工具，传入查询 "认知偏差"，从匹配的文件中提取上下文并归纳要点。

示例二：创建或更新笔记

用户：帮我在“Inbox”文件夹下创建一个新笔记，标题是“关于 MCP 协议的学习笔记”，内容先留空，加上标签“mcp”和“learning”。

AI 调用 obsidian_update_content（或 obsidian_append_content）创建文件，然后调用 obsidian_update_properties 添加标签。

示例三：批量属性管理

用户：把所有标签为“draft”的笔记，将其状态改为“review”，并更新“updated”时间戳。

AI 先使用 obsidian_complex_search 找到所有相关文件，然后逐一调用 obsidian_update_properties 进行更新。

示例四：知识图谱探索

用户：列出我知识库中所有的标签，并告诉我哪些标签使用最多。

AI 调用 obsidian_get_tags 工具，返回完整的标签列表及使用次数统计。

六、常见问题

问：连接失败，提示找不到 Local REST API 怎么办？

答：请确认：

1. Obsidian 正在运行。
2. Local REST API 插件 已安装并启用。
3. API 密钥已正确填入 OBSIDIAN_API_KEY 环境变量。
4. Obsidian 安全设置中的“启用 HTTPS”选项与你的 OBSIDIAN_PROTOCOL 配置一致。

问：为什么我搜索不到某些笔记？

答：可能是以下原因：

• 笔记位于空目录中：Local REST API 不会返回空目录的文件列表。
• 搜索的是二进制文件（如图片、PDF）：当前主要支持文本文件搜索。
• Obsidian 的缓存尚未更新：尝试重启 Obsidian。

问：更新属性时，我的旧标签被覆盖了怎么办？

答：obsidian_update_properties 工具的 replace 参数控制此行为。默认为 false，即新标签会与现有标签合并。如果你希望完全替换，需要将 replace 设置为 true。

问：可以在多台设备上使用同一个 Obsidian 知识库吗？

答：该服务器连接的是本地运行的 Obsidian 实例。如果你的知识库通过同步服务（如 Obsidian Sync）在多台设备上保持同步，你可以在每台设备上分别运行 Obsidian MCP Server。

七、总结

Obsidian MCP Server 为 Obsidian 用户打开了一扇全新的大门：它让精心维护的知识库不再是 AI 无法触及的孤岛，而是变成了 AI 可以理解、搜索和协助整理的动态资源。通过安全的 API 通信、灵活的搜索和属性管理工具，这个服务器将“第二大脑”与“AI 助手”真正连接在了一起。

对于每一位重度 Obsidian 用户和 AI 辅助工作流的实践者来说，花十分钟配置这个工具，你将获得一个能够读懂你所有笔记、帮你发现知识关联、并协助你持续优化知识结构的 AI 知识管家。这不仅仅是效率的提升，更是一种全新的知识管理范式。