MCP-Obsidian

使用说明

• 项目简介

  • MCP-Obsidian 是一个基于 MCP 标准的本地后端服务器，连接 Obsidian 知识库并向 MCP 兼容的 AI 助手（如 Claude、ChatGPT 等）提供对笔记的读取、写入、搜索、元数据管理等能力。服务器通过 JSON-RPC 处理请求，支持安全的路径检查、前置信息处理以及高效的笔记操作。

• 主要功能点

  • 资源管理：安全读取与写入笔记、读取/更新前端信息、列出 vault 目录结构、获取笔记信息与 Vault 统计等。
  • 工具注册与调用：暴露一组 MCP 工具，例如 read_note、write_note、patch_note、list_directory、delete_note、search_notes、move_note、move_file、read_multiple_notes、update_frontmatter、get_notes_info、get_frontmatter、manage_tags、get_vault_stats 等，支持输入校验与结构化响应。
  • Prompt 模板与渲染（可扩展）：支持基于笔记上下文的提示模板渲染与上下文提供，方便与 LLM 的对话模式对接。
  • 安全与合规：实现路径过滤、前端信息校验、删除确认、只暴露受信任的笔记格式（.md、.markdown、.txt），并对系统目录、敏感文件进行严格屏蔽。
  • 多传输协议支持：当前通过标准输入/输出（stdio）进行通信，便于在本地开发与集成测试环境中运行，同时具备在未来扩展到 SSE、WebSocket 等传输方式的潜力。

• 安装步骤

  • 需要 Node.js 运行时，推荐 v18 及以上版本。
  • 直接使用 npx 运行：
    • npx @mauricio.wolff/mcp-obsidian /path/to/your/obsidian/vault
  • 本地开发或自定义构建时，可以克隆仓库、安装依赖并自行启动服务，参照仓库中的服务入口与打包配置。

• 服务器配置

  • MCP 客户端要连接该 MCP 服务器，需在客户端的配置中指定启动命令及参数，使其通过 MCP 与 Obsidian 的服务器建立连接。
  • 具体配置项（示例描述，非代码）：
    • name: obsidian
    • command: "npx"
    • args: ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
    • 说明：上述配置会让客户端通过 MCP 服务器注册 obsidian 服务，并将 vault 路径传递给服务器运行环境。不同客户端（Claude Desktop、Claude Code、OpenCode 等）对配置位置略有差异，请按各自客户端的文档进行设置。
  • 运行后服务器会显示版本信息，可通过 --version 或 -v 选项查询版本。

• 基本使用方法

  • 启动服务器：将 vault 路径指向本地 Obsidian Vault，运行服务器 (如通过 npx 命令启动)。
  • 与 AI 客户端对话：在 AI 客户端配置了 MCP 服务器之后，即可通过自然语言指令交互，例如：
    • 读取笔记：读取某个笔记的内容与 frontmatter。
    • 写入/修改笔记：创建、追加、前置写入并可携带 frontmatter。
    • 管理标签：读取、添加、移除笔记中的标签（包括 frontmatter 与内联标签）。
    • 搜索笔记：按内容与/或 frontmatter 进行检索，支持多词检索与 BM25 相关性排序。
    • 其他批量与元数据操作：读取多篇笔记、获取前端信息、获取 vault 统计等。
  • 测试与调试：在开发阶段可使用 MCP Inspector 等工具对服务器进行请求测试，确保输入输出结构与错误信息符合预期。