Obsidian 本地 MCP 服务器插件

关键词

模型上下文协议知识图谱后端JSON-RPCObsidian 插件后端跨会话管理

使用说明内容（Markdown格式）

  • 项目简介

    • 该仓库实现了一个 Obsidian 插件级的 MCP 服务器端，核心职责是以标准化的 JSON-RPC 形式向 LLM 客户端提供百科全书式的上下文信息和能力，包括对 vault 中的资源（Notes、数据等）的访问数据、工具的注册与调用、以及 Prompt 模板的渲染与使用。服务器支持会话管理、能力声明，并可通过 HTTP/HTTPS 提供传输。客户端可以通过配置 MCP 服务器来读取资源、执行工具、获取和渲染提示模板等。

  • 主要功能点

    • MCP 核心协议实现：接收 MCP 格式的请求（如初始化、资源读取、工具调用等）并返回符合 MCP 规范的 JSON-RPC 响应。
    • 资源、工具、提示的托管与渲染：服务器端提供资源和工具的清单、对外提供资源读取能力，以及可执行的工具入口，且可渲染 Prompts/模板给 LLM 客户端。
    • 会话与并发支持：内置会话管理、单服务器和服务器池（多路并发服务实例）模式，能处理并发连接与请求分发。
    • 多传输与传输安全：HTTP(REST/JSON-RPC) 为主传输，支持 HTTPS，并提供端对端的认证与 TLS 设置的选项（包括自签证书处理）。
    • 安全与合规：引入 VaultSecurityManager、SecureObsidianAPI 等安全封装，支持只读模式、路径白/黑名单、以及对以 .mcpignore 的路径排除等机制。
    • Dataview 与资源扩展：在可用时集成 Dataview 工具，能够通过 Dataview 的 DQL 查询来丰富资源与数据访问能力。
    • 工具与工作流：内置多个语义工具组，覆盖 Vault 操作、图查询、视图与数据读取等能力，允许 LLM 客户端灵活组合使用。
    • 测试与健壮性：提供了针对 MCP 服务器、路由、递归拷贝、只读模式等功能的测试用例，帮助验证实现的正确性与稳定性。

  • 安装步骤

    1. 在 Obsidian 中启用插件
      • 通过社区插件安装：在设置中启用“Semantic MCP”插件（待发布阶段的可用版本）。
      • 也可通过 BRAT 启用 beta 流程，将仓库中的插件接入到 Obsidian 的开发环境中进行测试。
    2. 启动插件
      • 启动 Obsidian 后，若设置了 HTTP/HTTPS，MCP 服务器会在插件初始化时启动。
      • 服务器启动成功后，控制台会显示 MCP 服务的启动信息，浏览器/客户端即可通过配置连接到 http(s)://localhost:端口/mcp 进行通信。
    3. 客户端连接配置
      • 客户端需要配置一个 MCP 服务器项来连接到 Obsidian 插件中暴露的 MCP 端口，示例配置如下（供参考、非正式直接运行代码）：
        • 服务器名称: Obsidian Vault MCP
        • 命令: npx
        • 参数: ["mcp-remote", "http://localhost:3001/mcp"]
        • 如需使用 TLS/认证，请在参数中指定 header，例如 Authorization: Bearer YOUR_API_KEY；若使用自签证书可设置 NODE_TLS_REJECT_UNAUTHORIZED=0 环境变量。
    4. 使用与验证
      • 启动并连接后，向 MCP 服务器发送请求以获取资源、调用工具、获取 Prompts 等，进行对话式 AI 的上下文注入与能力调用。
      • 如遇端口冲突，插件具备自动切换端口的能力（在确保端口不被占用的前提下），并可在 UI 中给出切换提示。

  • 服务器配置（示意性 JSON 文本，供 MCP 客户端参考，不是必需直接运行的客户端代码）

    • 服务器名称示例：Obsidian Vault MCP
    • 启动配置（示意文本，非代码块）：
      { "mcpServers": { "obsidian-vault": { "name": "Obsidian Vault MCP", "command": "npx", "args": ["mcp-remote", "http://localhost:3001/mcp"] } } } 说明:
    • 该配置用于 MCP 客户端连接到 Obsidian 插件中暴露的 MCP 端点。若需要开启 TLS/认证，可将 header 参数加入 args，并在运行环境中设置相应的密钥或证书信任策略。
    • 客户端本身通常不需要直接操作服务器端的实现细节，更多是读取服务器的地址、端口及认证信息等元数据来建立连接。
    • 若需要自定义不同 vault 的并发连接或不同权限集合，可以在设置中配置相关安全策略与访问控制。

  • 基本使用方法

    • 启动阶段
      • 安装并启用插件后，确保 Obsidian 正在运行，HTTP/HTTPS 服务开启（依据设置）。
      • 服务器启动成功后，记录端口号和协议（HTTP/HTTPS）。
    • 与 AI 客户端交互
      • 使用客户端向 MCP 服务器发起请求（如资源读取、工具调用、读取资源等），插件将按照 MCP 协议返回统一格式的响应。
    • 安全与权限
      • 使用只读模式时，写操作会被阻断并返回相应的安全提示。 通过配置 .mcpignore，可以对特定路径实现自定义排除策略，保护敏感数据。
    • 进阶特性
      • 在可用 Dataview 时，Dataview 工具可用于更强的查询与数据挖掘。
      • 支持并发会话模式，适合多客户端并发访问，提升并发能力。
    • 常见任务
      • 查询 vault 信息、遍历知识图谱、执行 Vault 操作（如读取、写入、更新等）、汇总并渲染提示模板。

  • 备注

    • MCP 客户端与服务器之间的交互采用标准的 JSON-RPC 风格，服务端会根据不同的请求调用相应的工具、读取资源、或渲染提示模板。
    • 该实现包含服务器端的多种能力：单服务器与服务器池模式、会话管理、认证与安全策略、Dataview 集成等，具备完整的 MCP 服务端能力。

服务器信息

访问项目