Obsidian MCP Server - 增强版

增强版的Obsidian MCP Server，支持Claude.ai远程集成、Tailscale支持以及高级查询功能！

🔥 增强分支通知： 这是基于优秀的cyanheads/obsidian-mcp-server的增强版本，增加了专门针对远程Claude.ai集成、高级任务查询以及通过Tailscale实现的安全性的新特性。

一个MCP（模型上下文协议）服务器，提供对您的Obsidian保险库的全面访问。它使LLMs和AI代理能够通过Obsidian本地REST API插件读取、写入、搜索和管理您的笔记和文件。

基于cyanheads/mcp-ts-template，此服务器遵循模块化架构，并具有强大的错误处理、日志记录和安全特性。

🚀 增强功能（此分支）

🏛️ 多保险库支持

通过单个MCP服务器同时访问多个Obsidian保险库：

• 多保险库管理：同时连接到不同端口上的多个Obsidian实例
• 保险库特定路由：工具根据vault参数自动路由到正确的保险库
• 独立认证：每个保险库有单独的API密钥，并且有一个集中的MCP认证
• 向后兼容：现有的单保险库配置继续无变化地工作
• 动态配置：基于JSON的保险库配置，带有验证和错误处理

🌐 Claude.ai远程集成

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

• 无状态HTTP模式：专为Claude.ai兼容性设计的状态传输（MCP_HTTP_STATELESS=true）
• 会话模式：传统的会话管理用于其他MCP客户端
• 简化认证：使用专用的MCP_AUTH_KEY进行服务器访问
• 零配置：开箱即用与Claude.ai远程MCP服务器
• 生产就绪：企业级稳定性和错误处理

🔒 Tailscale安全远程访问

从任何地方安全地访问您的Obsidian保险库：

• Tailscale Funnel集成：带有自动证书的加密HTTPS端点
• 端到端加密：所有流量通过Tailscale网络加密
• 无需端口转发：不需要任何网络配置
• 访问控制：内置的Tailscale ACL支持企业安全性

📊 增强的任务及查询系统

超越原始版本的高级查询能力：

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

🔧 生产监控及可靠性

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

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

🚀 核心功能：Obsidian工具 🛠️

此服务器为您的AI提供了与您的Obsidian保险库交互的专用工具：

工具名称	描述	关键特性
obsidian_read_file	检索指定文件的内容和元数据。	- 以markdown或json格式读取。<br/>- 路径不区分大小写。<br/>- 包括文件统计信息（创建/修改时间）。
obsidian_update_file	使用全文件操作修改笔记。	- append，prepend或overwrite内容。<br/>- 如果文件不存在，可以创建文件。<br/>- 通过路径、活动笔记或周期性笔记定位文件。
obsidian_search_replace	在目标笔记中执行查找和替换操作。	- 支持字符串或正则表达式搜索。<br/>- 可选的大小写敏感、整个单词和替换所有出现。
obsidian_global_search	在整个保险库中执行搜索。	- 文本或正则表达式搜索。<br/>- 根据路径和修改日期过滤。<br/>- 分页结果。
obsidian_list_files	列出指定保险库文件夹内的文件和子目录。	- 根据文件扩展名或名称正则表达式过滤。<br/>- 提供目录的格式化树视图。
obsidian_manage_frontmatter	原子化管理笔记的YAML前缀。	- get，set或delete前缀键。<br/>- 避免为了元数据更改而重写整个文件。
obsidian_manage_tags	添加、删除或列出笔记的标签。	- 管理YAML前缀和内联内容中的标签。
obsidian_delete_file	从保险库中永久删除指定文件。	- 为了安全起见，路径不区分大小写。
obsidian_dataview_query	对您的保险库执行Dataview DQL查询。	- 使用Dataview语法运行TABLE，LIST查询。<br/>- 根据标签、前缀和日期查询笔记。<br/>- 生成报告和分析。
obsidian_task_query	搜索和分析您保险库中的任务。	- 根据状态、日期范围、优先级过滤。<br/>- 多种输出格式。<br/>- 提取任务元数据（截止日期、标签）。

---

目录

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

概述

Obsidian MCP Server充当桥梁，允许理解模型上下文协议（MCP）的应用程序（MCP客户端）——如高级AI助手（LLMs）、IDE扩展或自定义脚本——直接且安全地与您的Obsidian保险库交互。

而不是复杂的脚本或手动交互，您的工具可以利用此服务器来：

• 自动化保险库管理：读取笔记，更新内容，管理前缀和标签，跨文件搜索，列出目录，编程方式删除文件。
• 将Obsidian集成到AI工作流中：使LLMs能够访问和修改您的知识库作为其研究、写作或编码任务的一部分。
• 构建自定义的Obsidian工具：创建以新颖方式与您的保险库数据交互的外部应用程序。

基于强大的mcp-ts-template，此服务器提供了一种标准化、安全且高效的方式，通过MCP标准暴露Obsidian功能。它通过与运行在您的保险库内部的强大Obsidian本地REST API插件通信来实现这一点。

开发者提示：此存储库包含一个.clinerules文件，作为您的LLM编码代理的开发者速查表，快速参考代码库模式、文件位置和代码片段。

功能

核心实用工具

利用mcp-ts-template提供的强大实用工具：

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

Obsidian集成

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

安装

先决条件

1. Obsidian：您需要安装Obsidian。
2. Obsidian本地REST API插件：在您的Obsidian保险库中安装并启用Obsidian本地REST API插件。
3. API密钥：在Obsidian的本地REST API插件设置中配置一个API密钥。您需要此密钥来配置服务器。
4. Node.js & npm：确保您已安装Node.js（推荐18或更高版本）和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代码到dist/目录中的JavaScript，并使入口点可执行。

配置

环境变量

使用环境变量配置服务器。

这些变量必须在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
M_	MCP_HTTP_STATELESS	为Claude.ai兼容性启用无状态模式。	否
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动作的HTTP路径（POST）。	否	/chatgpt/actions
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文件
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文件
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",
    保险库名称："个人保险库",
    "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实例：在不同的端口上安装本地REST API插件
3. 获取API密钥：从每个Obsidian实例的插件设置中提取API密钥
4. 配置保险库：更新.env中的OBSIDIAN_VAULTS JSON配置
5. 启动服务器：npm run start:http
6. 通过Claude.ai访问：使用您的Tailscale URL和MCP_AUTH_KEY

连接到Obsidian API

单保险库模式

要在单保险库模式下连接，配置基础URL（OBSIDIAN_BASE_URL）和API密钥（OBSIDIAN_API_KEY）。Obsidian本地REST API插件提供两种连接类型：

1. 加密（HTTPS）：

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