Obsidian Mcp For Claude.ai (web)

Obsidian MCP 服务 - 增强版

增强版 Obsidian MCP 服务，支持 Claude.ai 远程集成、Tailscale 和高级查询功能！

🔥 增强版分支说明： 这是优秀的 cyanheads/obsidian-mcp-server 的增强版本，新增专为 Claude.ai 远程集成、高级任务查询和通过 Tailscale 实现安全访问而设计的功能。

这是一个 MCP（Model Context Protocol）服务，可全面访问你的 Obsidian 知识库。它通过 Obsidian Local REST API plugin，让大模型和 AI Agent 能够读取、写入、搜索和管理你的笔记与文件。

此服务基于 cyanheads/mcp-ts-template 构建，采用模块化架构，具备完善的错误处理、日志记录和安全功能。

🚀 增强功能（此分支）

🏛️ 多知识库支持

通过单个 MCP 服务同时访问多个 Obsidian 知识库：

• 多知识库管理：同时连接运行在不同端口上的多个 Obsidian 实例
• 知识库专属路由：工具根据 vault 参数自动路由到正确的知识库
• 独立身份验证：每个知识库使用单独的 API 密钥，并通过 MCP 进行集中身份验证
• 向后兼容：现有的单知识库配置无需更改即可继续使用
• 动态配置：采用基于 JSON 的知识库配置，并提供验证和错误处理

🌐 Claude.ai 远程集成

与 Claude.ai 的 Remote MCP 功能完美集成：

• 无状态 HTTP 模式：为兼容 Claude.ai 提供专用的无状态传输（MCP_HTTP_STATELESS=true）
• 基于会话的模式：为其他 MCP 客户端提供传统的会话管理
• 简化身份验证：使用专用的 MCP_AUTH_KEY 访问服务
• 零配置：开箱即用，适用于 Claude.ai Remote MCP 服务
• 可用于生产环境：具备企业级稳定性和错误处理

🔒 Tailscale 安全远程访问

随时随地安全访问你的 Obsidian 知识库：

• Tailscale Funnel 集成：提供具有自动证书的安全 HTTPS 端点
• 端到端加密：所有流量均通过 Tailscale 网络加密
• 无需端口转发：无需任何网络配置
• 访问控制：内置 Tailscale ACL 支持，满足企业安全需求

📊 增强的任务与查询系统

提供超越原版的高级查询功能：

• Tasks 插件集成：与 Obsidian Tasks 插件深度集成
• 高级日期解析：识别自然语言日期
• 优先级检测：解析视觉和文本格式的优先级
• 多种输出格式：支持表格、列表和摘要视图

🔧 生产监控与可靠性

企业级监控和自动重启功能：

• 健康检查脚本：全面验证组件（scripts/health-check.sh）
• 智能监控：通过进程生命周期管理实现自动重启（scripts/monitor-mcp.sh）
• macOS 自动启动：配置启动代理以实现系统启动时运行（scripts/setup-autostart.sh）
• 动态端口管理：自动解决端口冲突（3010-3013 范围）
• 增强日志记录：详细的连接调试和 API 密钥验证

🚀 核心能力：Obsidian 工具 🛠️

此服务为你的 AI 配备了专用工具，可与 Obsidian 仓库交互：

工具名称	描述	主要功能
obsidian_read_file	获取指定文件的内容和元数据。	- 以 markdown 或 json 格式读取。 - 路径大小写不敏感的回退匹配。 - 包含文件统计信息（创建／修改时间）。
obsidian_update_file	通过整文件操作修改笔记。	- append、prepend 或 overwrite 内容。 - 文件不存在时可以创建文件。 - 按路径、当前活动笔记或周期笔记定位文件。
obsidian_search_replace	在目标笔记中执行查找和替换操作。	- 支持字符串或正则表达式搜索。 - 可设置区分大小写、整词匹配和替换所有匹配项。
obsidian_global_search	在整个仓库中执行搜索。	- 文本或正则表达式搜索。 - 按路径和修改日期筛选。 - 分页显示结果。
obsidian_list_files	列出指定仓库文件夹中的文件和子目录。	- 按文件扩展名或名称正则表达式筛选。 - 提供格式化的目录树视图。
obsidian_manage_frontmatter	原子化管理笔记的 YAML frontmatter。	- get、set 或 delete frontmatter 键。 - 修改元数据时无需重写整个文件。
obsidian_manage_tags	为笔记添加、移除或列出标签。	- 管理 YAML frontmatter 和行内内容中的标签。
obsidian_delete_file	从仓库中永久删除指定文件。	- 为安全起见，提供路径大小写不敏感的回退匹配。
obsidian_dataview_query	对你的仓库执行 Dataview DQL 查询。	- 使用 Dataview 语法运行 TABLE、LIST 查询。 - 按标签、frontmatter 和日期查询笔记。 - 生成报告和分析结果。
obsidian_task_query	搜索和分析仓库中的任务。	- 按状态、日期范围和优先级筛选。 - 支持多种输出格式。 - 提取任务元数据（截止日期、标签）。

---

目录

| 概述 | 功能 | 安装 | | 配置 | 项目结构 | Vault 缓存服务 | | 工具 | 资源 | 开发 | 许可证 |

概述

Obsidian MCP 服务充当桥梁，让能够理解模型上下文协议（MCP）的应用程序（MCP 客户端）——例如高级 AI 助手（大模型）、IDE 扩展或自定义脚本——能够直接、安全地与您的 Obsidian 知识库交互。

无需编写复杂脚本或手动操作，您的工具便可借助此服务：

• 自动管理知识库：以编程方式读取笔记、更新内容、管理 frontmatter 和标签、搜索文件、列出目录以及删除文件。
• 将 Obsidian 集成到 AI 工作流中：让大模型在研究、写作或编码任务中访问和修改您的知识库。
• 构建自定义 Obsidian 工具：创建以新颖方式与知识库数据交互的外部应用程序。

此服务基于稳健的 mcp-ts-template 构建，为通过 MCP 标准公开 Obsidian 功能提供了一种标准化、安全且高效的方式。它通过与知识库中运行的强大 Obsidian Local REST API 插件通信来实现这一点。

开发者说明：此代码库包含一个 .clinerules 文件，作为面向 LLM 编码 Agent 的开发者速查手册，提供代码库模式、文件位置和代码片段的快速参考。

功能

核心实用工具

借助 mcp-ts-template 提供的稳健实用工具：

• 日志记录：结构化、可配置的日志记录（文件轮换、控制台、MCP 通知），并支持敏感数据脱敏。
• 错误处理：集中式错误处理、标准化错误类型（McpError）和自动日志记录。
• 配置：加载环境变量（dotenv）并进行全面验证。
• 输入验证/清理：使用 zod 进行架构验证，并使用自定义清理逻辑。
• 请求上下文：通过唯一请求 ID 跟踪和关联操作。
• 类型安全：通过 TypeScript 和 Zod 架构强制执行严格类型检查。
• HTTP 传输选项：原生 Node.js HTTP 服务，支持会话管理、CORS 和 API 密钥身份验证。

Obsidian 集成

• Obsidian Local REST API 集成：通过由 ObsidianRestApiService 管理的 HTTP 请求，直接与 Obsidian Local REST API 插件通信。
• 全面的命令覆盖：将关键知识库操作公开为 MCP 工具（参见 工具部分）。
• 知识库交互：支持读取、更新（追加、前置、覆盖）、搜索（全局文本/正则表达式、搜索/替换）、列出、删除，以及管理 frontmatter 和标签。
• 灵活的目标定位：工具可以按路径、Obsidian 中当前活动的文件或周期性笔记（每日、每周等）定位文件。
• Vault 缓存服务：智能内存缓存，可提升性能和可靠性。它会缓存知识库内容，在实时 API 失效时为全局搜索工具提供回退方案，并定期刷新以保持同步。
• 安全功能：文件操作支持不区分大小写的路径回退，并明确区分修改类型（追加、覆盖等）。

安装

前置条件

1. Obsidian：需要安装 Obsidian。
2. Obsidian Local REST API Plugin：在 Obsidian 知识库中安装并启用 Obsidian Local REST API plugin。
3. API 密钥：在 Obsidian 的 Local REST API plugin 设置中配置 API 密钥。配置服务时需要使用此密钥。
4. Node.js 和 npm：确保已安装 Node.js（建议使用 v18 或更高版本）和 npm。
5. Tailscale（用于远程访问）：安装 Tailscale，并启用 Tailscale Funnel，以便安全地与 Claude.ai 集成。

💡 快速设置：如需设置开机自动启动，请在安装后参阅自动启动设置指南。

安装

1. 克隆此增强版仓库：

   git clone https://github.com/BoweyLou/obsidian-mcp-server-enhanced.git
   cd obsidian-mcp-server-enhanced
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

   此操作会将 TypeScript 代码编译为 JavaScript，并输出到 dist/ 目录，同时使入口点可执行。

配置

环境变量

使用环境变量配置服务。

必须在 MCP 客户端配置（例如 cline_mcp_settings.json）中设置这些变量，或者在启动服务前设置到环境中（直接运行时）。

如果直接运行，可以在项目根目录的 .env 文件中设置这些变量，也可以直接在环境中设置。

变量	描述	必需	默认值
MCP_AUTH_KEY	用于 Claude.ai 远程 MCP 访问的身份验证密钥。使用 openssl rand -hex 32 生成	是（远程）	undefined
OBSIDIAN_VAULTS	用于多知识库模式的知识库配置 JSON 数组。	是（多知识库）	undefined
OBSIDIAN_API_KEY	来自 Obsidian 插件的 API 密钥（仅限单知识库模式）。	是（单知识库）	undefined
OBSIDIAN_BASE_URL	Obsidian API 的基础 URL（仅限单知识库模式）。	是（单知识库）	http://127.0.0.1:27123
MCP_TRANSPORT_TYPE	服务传输方式：stdio 或 http。	否	http
MCP_HTTP_PORT	HTTP 服务的端口。	否	3010
MCP_HTTP_HOST	HTTP 服务的主机。	否	127.0.0.1
MCP_HTTP_STATELESS	启用无状态模式以兼容 Claude.ai。	否	false
MCP_ALLOWED_ORIGINS	以逗号分隔的 CORS 源。生产环境中请设置。	否	（无）
CHATGPT_LAYER_ENABLED	设置为 true，以提供 ChatGPT 清单和 JSON 操作端点。	否	false
CHATGPT_MANIFEST_PATH	用于公开 ChatGPT 清单 JSON 的 HTTP 路径。	否	/.well-known/obsidian-chatgpt-manifest.json
CHATGPT_ACTIONS_PATH	用于 ChatGPT JSON 操作（POST）的 HTTP 路径。	否	/chatgpt/actions
CHATGPT_FACADE_TOKEN_TTL_SECONDS	ChatGPT 外观层访问令牌的有效期。	否	3600
CHATGPT_FACADE_REFRESH_TOKEN_TTL_SECONDS	ChatGPT 外观层刷新令牌的有效期。	否	2592000
CHATGPT_FACADE_SCOPES	以逗号分隔的 ChatGPT 外观层权限范围。仅对明确受信任的客户端添加写入权限范围。	否	obsidian:read
MCP_LOG_LEVEL	日志级别（debug、info、error 等）。	否	info
OBSIDIAN_VERIFY_SSL	设置为 false 以禁用 SSL 验证。	否	true
OBSIDIAN_ENABLE_CACHE	设置为 true 以启用内存中的知识库缓存。	否	true
OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN	知识库缓存的刷新间隔，单位为分钟。	否	10

多知识库配置

服务同时支持单知识库模式（向后兼容）和多知识库模式：

单知识库模式（旧版）

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_API_KEY=your-obsidian-plugin-api-key
OBSIDIAN_BASE_URL=http://127.0.0.1:27123
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

多知识库模式（推荐）

# .env file
MCP_AUTH_KEY=your-generated-mcp-auth-key
OBSIDIAN_VAULTS='[
  {
    "id": "work",
    "name": "Work Vault", 
    "apiKey": "work-vault-api-key",
    "baseUrl": "http://127.0.0.1:27123",
    "verifySsl": false
  },
  {
    "id": "personal",
    "name": "Personal Vault",
    "apiKey": "personal-vault-api-key", 
    "baseUrl": "http://127.0.0.1:27122",
    "verifySsl": false
  }
]'
MCP_TRANSPORT_TYPE=http
MCP_HTTP_STATELESS=true

设置流程

1. 生成 MCP 身份验证密钥：openssl rand -hex 32
2. 配置多个 Obsidian 实例：在不同端口安装 Local REST API 插件
3. 获取 API 密钥：从每个 Obsidian 实例的插件设置中提取 API 密钥
4. 配置知识库：使用 OBSIDIAN_VAULTS JSON 配置更新 .env
5. 启动服务：npm run start:http
6. 通过 Claude.ai 访问：使用你的 Tailscale URL 和 MCP_AUTH_KEY

连接到 Obsidian API

单知识库模式

要以单知识库模式连接，请配置基础 URL（OBSIDIAN_BASE_URL）和 API 密钥（OBSIDIAN_API_KEY）。Obsidian Local REST API 插件提供两种连接类型：

1. 加密（HTTPS）：

   • 使用安全的 https:// 端点（例如，https://127.0.0.1:27124）
   • 对于自签名证书，需要设置 OBSIDIAN_VERIFY_SSL=false

2. 未加密（HTTP）- 推荐：

   • 使用 http:// 端点（例如，http://127.0.0.1:27123）
   • 设置更简单，无需进行 SSL 验证

多知识库模式

在多知识库模式下，请在 OBSIDIAN_VAULTS JSON 数组中为每个知识库单独配置其 API 密钥和基础 URL。每个知识库都可以按需使用 HTTP 或 HTTPS。

配置示例：

使用 HTTP 的单知识库配置：

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_API_KEY": "your-obsidian-api-key",
  "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}

多知识库配置：

"env": {
  "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
  "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work\",\"apiKey\":\"work-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal\",\"apiKey\":\"personal-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]"
}

本地 MCP 客户端设置（可选）

注意：对于 Claude.ai 远程 MCP 集成，请跳过本节，改用 Tailscale 远程访问设置。

对于本地 MCP 客户端（例如，Cline），请将以下内容添加到设置中（例如，cline_mcp_settings.json）：

单知识库配置：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_API_KEY": "your-obsidian-api-key",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

多知识库配置：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server-enhanced/dist/index.js"],
      "env": {
        "MCP_AUTH_KEY": "your-generated-mcp-auth-key",
        "OBSIDIAN_VAULTS": "[{\"id\":\"work\",\"name\":\"Work Vault\",\"apiKey\":\"work-api-key\",\"baseUrl\":\"http://127.0.0.1:27123\"},{\"id\":\"personal\",\"name\":\"Personal Vault\",\"apiKey\":\"personal-api-key\",\"baseUrl\":\"http://127.0.0.1:27122\"}]",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

🌐 远程访问设置（Tailscale）

要从任何地方远程访问你的 Obsidian 知识库，可以使用 Tailscale 安全地通过互联网公开 MCP 服务。

先决条件

1. Tailscale 账户：在 tailscale.com 注册
2. 安装 Tailscale：在运行 MCP 服务的机器上安装 Tailscale
3. 启用 Tailscale Funnel：为你的账户启用 Tailscale Funnel

设置步骤

1. 生成 MCP 身份验证密钥：

   openssl rand -hex 32
   

2. 配置环境：使用生成的密钥设置 .env 文件：

   MCP_AUTH_KEY=your-generated-auth-key
   MCP_TRANSPORT_TYPE=http
   MCP_HTTP_PORT=3010
   MCP_HTTP_STATELESS=true
   

3. 配置知识库：设置单知识库或多知识库配置（参见多知识库配置）

4. 启动 MCP 服务：

   npm run build && npm run start:http
   

5. 启用 Tailscale Funnel：

   tailscale funnel 3010
   

6. 获取你的公共 URL：查看你的 Tailscale 设备 URL：

   tailscale status --self | grep "Funnel on"
   

Claude.ai 远程 MCP 配置

使用 MCP 身份验证密钥，将以下内容添加到 Claude.ai 远程 MCP 服务：

单知识库设置：

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Vault"
}

多知识库设置：

{
  "url": "https://your-device.your-tailnet.ts.net/mcp?api_key=your-mcp-auth-key",
  "name": "Obsidian Multi-Vault"
}

身份验证说明：Claude.ai 远程 MCP 使用 MCP_AUTH_KEY 对服务进行身份验证。各知识库操作使用环境中配置的知识库专属 API 密钥。

安全注意事项

• 双重身份验证：MCP 服务通过 MCP_AUTH_KEY 进行身份验证，知识库通过各自的 API 密钥进行身份验证
• Tailscale 加密：所有流量均由 Tailscale 进行端到端加密
• 专用网络：只有你能通过自己的 Tailscale 网络访问此服务
• 自动 SSL：Tailscale Funnel 提供自动 HTTPS 证书
• 知识库隔离：每个知识库都使用自己的 API 密钥进行安全访问控制

使用示例

设置完成后，你可以通过 Claude.ai 远程使用工具：

单知识库命令（使用默认知识库）：

Use obsidian_task_query to show me tasks due today with format="table"

多知识库命令（指定知识库）：

Use obsidian_task_query with vault="work" to show me work tasks due today

Use obsidian_read_file with filePath="daily-note.md" and vault="personal" 

Use obsidian_dataview_query with vault="work" to run: TABLE file.name FROM #meeting WHERE file.cday = date(today)

🚀 专业提示：在生产环境中使用时，请设置开机自动启动，这样服务和 Tailscale Funnel 就会自动启动，无需手动操作。

ChatGPT Connector Facade

Claude 和本地 MCP 客户端可以直接连接到 /mcp。托管的 ChatGPT 连接器应改用单独的 obsidian-chatgpt facade。facade 在内部复用现有的知识库、搜索和任务逻辑，但使用独立的进程、端口、OAuth/PKCE 授权流程、范围限定的功能以及写入审计日志。

通过公共 HTTPS 或 Tailscale Funnel 路由时，请使用 facade。除非明确用于本地/开发测试，否则请将完整的 MCP 服务限制在 localhost 或仅限私有 tailnet 的路由上。

启动 Facade

配置公共资源 URL 和管理员审批密钥，然后启动 facade：

export CHATGPT_FACADE_PUBLIC_URL="https://your-device.your-tailnet.ts.net"
export CHATGPT_FACADE_ADMIN_SECRET="$(openssl rand -hex 24)"
npm run build
npm run start:chatgpt

如果同一个 Funnel 主机名还公开了另一个 ChatGPT 连接器，请为此 facade 设置一个路径范围的资源 URL，例如 https://your-device.your-tailnet.ts.net/obsidian，并将 /obsidian 前缀路由到 facade 端口。对于这种配置，facade 会同时提供根路径和带路径限定的 well-known 元数据路径。在这种共享主机配置中，请使用 https://your-device.your-tailnet.ts.net/obsidian/mcp 创建连接器。

检查运行状况：

curl "http://127.0.0.1:3020/health"

如果要在没有实时 Obsidian API 的情况下测试 facade 的 HTTP 接口，请设置 CHATGPT_FACADE_SKIP_OBSIDIAN_CHECK=true。正常运行时请勿设置此变量。

通过 Funnel 仅公开 facade：

make tailscale-funnel-chatgpt

OAuth 和 Scopes

facade 会发布 OAuth 发现元数据：

• /.well-known/oauth-protected-resource
• /.well-known/oauth-authorization-server
• /.well-known/openid-configuration

授权码、访问令牌和刷新令牌的哈希会存储在本地的 CHATGPT_FACADE_STORE_PATH 下，而不是存储原始令牌。初始令牌交换必须使用 PKCE S256；facade 支持刷新令牌轮换，并会在执行操作前按资源、过期时间和 scope 验证 bearer 令牌。

Scopes：

• obsidian:read：search、fetch、task_query、latest_note
• obsidian:write：create_task、update_task、append_note、create_note、create_daily_note
• obsidian:dangerous-write：overwrite_note

默认采用只读连接器配置，只需授予 obsidian:read 即可支持该配置。 除非明确授予 obsidian:dangerous-write，否则无法使用 overwrite_note。

门面操作

所有操作均使用 POST /chatgpt/actions，并通过 Authorization: Bearer <token> 进行身份验证。 它们接受可选的 vault 字段。默认公开接口特意设计得比完整的本地 MCP 工具集更精简。

操作	范围	描述
search	obsidian:read	带摘要的全局搜索，结果数量有限。
fetch	obsidian:read	按 vault 路径获取内容长度有限的笔记。
task_query	obsidian:read	支持 Tasks 插件的任务查询。
latest_note	obsidian:read	获取最近修改的笔记，可按路径限定范围。
create_task	obsidian:write	创建与 Tasks 插件兼容的任务。
update_task	obsidian:write	更新现有任务。
append_note	obsidian:write	在笔记内容前或后追加内容。
create_note	obsidian:write	创建笔记，不覆盖现有内容。
create_daily_note	obsidian:write	使用每日笔记模板创建今天或指定日期的每日笔记。
overwrite_note	obsidian:dangerous-write	为明确受信任的客户端提供整篇笔记覆盖功能。

HTTP 操作和门面 MCP 工具调用的成功响应使用相同的封装格式：

{
  "success": true,
  "action": "create_daily_note",
  "vault": "default",
  "resultPath": "Daily/2026-07-03.md",
  "data": {
    "filePath": "Daily/2026-07-03.md"
  }
}

写入操作会在已知受影响的 vault 路径时包含 resultPath。 创建任务和更新任务的操作还会在行号可用时包含 taskLineNumber。

写入操作会追加到本地 JSONL 审计日志 CHATGPT_FACADE_AUDIT_PATH。审计条目会记录操作、客户端 ID、范围、 目标路径、模式、结果路径、状态和经过长度限制的输入摘要；不会存储原始 ChatGPT 对话记录或完整笔记正文。运维人员可以使用以下命令检查最近的条目：

curl "http://127.0.0.1:3020/audit/recent?admin_secret=$CHATGPT_FACADE_ADMIN_SECRET"

旧版进程内层

设置 CHATGPT_LAYER_ENABLED=true 仍可在主 HTTP 传输上启用较早的进程内清单/操作层，以兼容本地/开发环境。 该层使用 MCP_AUTH_KEY 查询字符串身份验证，并公开更广泛的操作，包括覆盖页面。请勿将其用作推荐的托管式 ChatGPT 连接器方案。

项目结构

代码库在 src/ 目录中采用模块化结构：

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/        # Core MCP server logic and capability registration
│   ├── server.ts      # Server setup, transport handling, tool/resource registration
│   ├── resources/     # MCP Resource implementations (currently none)
│   ├── tools/         # MCP Tool implementations (subdirs per tool)
│   └── transports/    # Stdio and HTTP transport logic, auth middleware
├── services/          # Abstractions for external APIs or internal caching
│   ├── obsidianRestAPI/ # Typed client for Obsidian Local REST API
│   └── vaultManager/    # Multi-vault configuration and service management
├── types-global/      # Shared TypeScript type definitions (errors, etc.)
└── utils/             # Common utility functions (logger, error handler, security, etc.)

如需查看详细的文件树，请运行 npm run tree 或参阅 docs/tree.md。

Vault 缓存服务

此服务包含一个智能的内存缓存，旨在提升与 vault 交互时的性能和弹性。

用途和优势

• 性能：通过缓存文件内容和元数据，服务可以更快地执行搜索操作，尤其是在大型 vault 中。这减少了对 Obsidian Local REST API 的直接请求次数，带来更流畅的体验。
• 弹性：缓存可作为 obsidian_global_search 工具的备用方案。如果实时 API 搜索失败或超时，服务会无缝使用缓存提供结果，确保即使 Obsidian API 暂时无响应，搜索功能仍然可用。
• 效率：缓存经过高效设计。它会在启动时进行初次构建，然后定期在后台检查文件修改并刷新，从而保持较新的状态，同时避免持续进行大量 API 轮询。

工作原理

1. 初始化：启用后，VaultCacheService 会在内存中构建一个映射，其中包含保管库内所有 .md 文件的内容和修改时间。
2. 定期刷新：缓存会按可配置的间隔自动刷新（默认为 10 分钟）。刷新期间，它只会获取自上次检查以来新增或已修改文件的内容。
3. 主动更新：通过 obsidian_update_file 等工具修改文件后，服务会主动更新该文件的缓存，确保内容立即保持一致。
4. 搜索回退：obsidian_global_search 工具会先尝试实时 API 搜索。如果失败，则会自动回退到内存缓存进行搜索。

配置

缓存默认启用，但可以通过环境变量进行配置：

• OBSIDIAN_ENABLE_CACHE：设为 true（默认值）或 false，以启用或禁用缓存服务。
• OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN：设置定期后台刷新的间隔（分钟）。默认值为 10。

工具

Obsidian MCP Server 提供了一系列用于与一个或多个保管库交互的工具，可通过 Model Context Protocol 调用。

多知识库支持

所有工具都支持可选的 vault 参数，用于指定要操作的知识库：

• 默认行为：不提供 vault 参数时，工具使用第一个已配置的知识库
• 指定知识库：添加 vault: "vault-id" 以指定目标知识库
• 示例：obsidian_read_file(filePath="note.md", vault="work")

工具名称	描述	关键参数
obsidian_read_file	获取文件内容和元数据。	filePath、vault?、format?、includeStat?
obsidian_update_file	通过追加、前置或覆盖内容来修改文件。	targetType、content、vault?、targetIdentifier?、wholeFileMode
obsidian_search_replace	在笔记中执行搜索和替换操作。	targetType、replacements、vault?、useRegex?、replaceAll?
obsidian_global_search	搜索整个知识库中的内容。	query、vault?、searchInPath?、useRegex?、page?、pageSize?
obsidian_list_files	列出文件夹中的文件和子目录。	dirPath、vault?、fileExtensionFilter?、nameRegexFilter?
obsidian_manage_frontmatter	获取、设置或删除笔记 frontmatter 中的键。	filePath、operation、key、vault?、value?
obsidian_manage_tags	添加、移除或列出笔记中的标签。	filePath、operation、tags、vault?
obsidian_delete_file	从知识库中永久删除文件。	filePath、vault?
obsidian_dataview_query	对知识库执行 Dataview DQL 查询。	query、vault?、format?
obsidian_task_query	搜索和分析知识库中的任务。	vault?、status?、dateRange?、folder?、priority?、format?
obsidian_periodic_notes	创建和管理每日、每周、每月和每年笔记。	operation、periodType、vault?、date?、content?、append?
obsidian_block_reference	使用块引用并执行标题操作。	operation、filePath、vault?、heading?、content?、blockId?
obsidian_graph_analysis	分析笔记之间的连接和知识库关系。	operation、vault?、filePath?、minConnections?、maxDepth?
obsidian_template_system	通过变量替换使用模板创建文件。	operation、vault?、templatePath?、targetPath?、variables?
obsidian_smart_linking	获取智能链接建议和推荐。	operation、vault?、filePath?、content?、maxSuggestions?

注意：所有工具都支持全面的错误处理、多知识库路由，并返回结构化 JSON 响应。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

致谢

此增强版基于 cyanheads 在原始 obsidian-mcp-server 项目中的出色工作。所有核心功能和架构均归功于原作者。

此分支的增强内容：

• 多知识库支持：同时访问多个 Obsidian 知识库，并根据知识库进行路由
• Claude.ai 远程 MCP 集成与兼容性修复
• 集成 Tailscale Funnel，实现安全远程访问
• 增强 HTTP 传输层，并分离身份验证（MCP_AUTH_KEY）
• 集成 Tasks 插件，支持高级任务查询
• 5 种全新高级工具：周期性笔记、块引用、图谱分析、模板系统和智能链接
• 可用于企业环境的生产就绪配置

---