Obsidian MCP Server - Enhanced

黑曜石MCP服务器-增强型

  ](./CHANGELOG.md)   

增强的黑曜石MCP服务器，具有Claude.ai远程集成、Tailscale支持和高级查询功能！

🔥 增强分叉通知： 这是优秀的增强版 蓝头/黑曜石mcp服务器 通过Tailscale提供专为远程Claude.ai集成、高级任务查询和安全性量身定制的附加功能。

MCP（模型上下文协议）服务器，提供对黑曜石保险库的全面访问。使LLM和AI代理能够通过 黑名单本地REST API插件.

建立在 cyanheads/mcp-ts-template，此服务器遵循模块化架构，具有强大的错误处理、日志记录和安全功能。

🚀 增强功能（此分叉）

🏛️ 多保险库支持

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

• 多保险库管理：同时连接到不同端口上的多个Obsidian实例
• 保险库特定路由：工具会根据以下内容自动路由到正确的vault vault 参数
• 个人身份验证：每个保险库都有单独的API密钥，具有集中的MCP身份验证
• 向后兼容的：现有的单保险库配置继续保持不变
• 动态配置：基于JSON的vault配置，具有验证和错误处理功能

🌐 Claude.ai远程集成

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

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

🔒 Tailscale安全远程访问

从任何地方安全访问您的黑曜石保险库：

• 尾鳞片漏斗集成：使用自动证书保护HTTPS端点
• 端加密：所有流量均通过Tailscale网络加密
• 无端口转发：无需网络配置
• 访问控制：内置Tailscale ACL支持企业安全

📊 增强型任务与查询系统

超越原始的高级查询功能：

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

🔧 生产监控和可靠性

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

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

🚀 核心功能：黑曜石工具🛠️

此服务器为您的AI配备了专门的工具，以与您的黑曜石保险库进行交互：

-不区分大小写的路径回退。 -包括文件统计信息（创建/修改时间）。 | | obsidian_update_file |使用全文件操作修改注释。 | - append, prepend，或 overwrite 内容。 -如果文件不存在，可以创建文件。 -按路径、活动注释或定期注释定位文件。 | | obsidian_search_replace |在目标注释中执行搜索和替换操作。|-支持字符串或正则表达式搜索。 -区分大小写、整词和替换所有出现的选项。 | | obsidian_global_search |在整个保险库中执行搜索。|-文本或正则表达式搜索。 -按路径和修改日期过滤。 -分页结果。 | | obsidian_list_files |列出指定vault文件夹中的文件和子目录。|-按文件扩展名或名称正则表达式过滤。 -提供目录的格式化树视图。 | | obsidian_manage_frontmatter |原子化地管理笔记的YAML frontmatter。 | - get, set，或 delete 正面按键。 -避免因元数据更改而重写整个文件。 | | obsidian_manage_tags |添加、删除或列出注释的标记。|-管理YAML frontmatter和内联内容中的标签。 | | obsidian_delete_file |从vault中永久删除指定文件。|-不区分大小写的安全路径回退。 | | obsidian_dataview_query |对vault执行Dataview DQL查询。|-使用Dataview语法运行TABLE、LIST查询。 -按标签、封面、日期查询笔记。 -生成报告和分析。 | | obsidian_task_query |在整个vault中搜索和分析任务。|-按状态、日期范围、优先级筛选。 -多种输出格式。 -提取任务元数据（截止日期、标签）。 |

______________________________________________________________________

目录

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

概述

黑曜石MCP服务器充当桥梁，允许理解模型上下文协议（MCP）的应用程序（MCP客户端）（如高级AI助手（LLM）、IDE扩展或自定义脚本）直接安全地与您的黑曜石库交互。

您的工具可以利用此服务器来：

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

建立在坚固的基础上 mcp-ts-template，此服务器提供了一种标准化、安全且高效的方式，通过MCP标准公开黑曜石功能。它通过与有权势的人沟通来实现这一点 黑名单本地REST API插件 在你的保险库里奔跑。

开发者说明：此存储库包括 .微规则 该文件作为LLM编码代理的开发人员备忘单，可快速参考代码库模式、文件位置和代码片段。

特性

核心工具

利用 mcp-ts-template:

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

黑曜石融合

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

安装

先决条件

1. 黑曜石：您需要安装黑曜石。
2. 黑名单本地REST API插件：安装并启用 黑名单本地REST API插件 在你的黑曜石金库里。
3. API密钥：在Obsidian中的本地REST API插件设置中配置API密钥。您需要此密钥来配置服务器。
4. Node.js和npm：确保安装了Node.js（建议使用v18或更高版本）和npm。
5. 尾鳞 （用于远程访问）：安装 尾鳞 并启用Tailscale Funnel以实现安全的远程Claude.ai集成。

💡 快速设置：有关启动时的自动启动，请参阅 自动启动设置指南 安装后。

安装

1. 克隆此增强的存储库：

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

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

这将TypeScript代码编译为JavaScript dist/ 目录，并使入口点可执行。

配置

环境变量

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

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

如果直接运行，可以在 .env 文件位于项目根目录中或直接位于您的环境中。

多保险库配置

服务器支持单保险库（向后兼容）和多保险库模式：

单保险库模式（传统）

# .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. 配置多个黑曜石实例：在不同端口上安装本地REST API插件
3. 获取API密钥：从每个Obsidian实例的插件设置中提取API密钥
4. 配置保险库：更新 .env 随着 OBSIDIAN_VAULTS JSON配置
5. 启动服务器: npm run start:http
6. 通过Claude.ai访问：使用MCP_AUTH_KEY的Tailscale URL

正在连接到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 用于自签名证书

1. 非加密（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集成，跳过本节并使用 尾秤远程访问设置 相反。

对于本地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在互联网上安全地公开您的MCP服务器。

先决条件

1. 尾秤账户：注册地址： tailscale.com
2. 尾秤已安装：在运行MCP服务器的计算机上安装Tailscale
3. 尾秤漏斗已启用：为您的帐户启用Tailscale漏斗

设置步骤

1. 生成MCP认证密钥:

   openssl rand -hex 32

1. 配置环境：设置您的 .env 带有生成密钥的文件：

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

1. 配置保险库：设置单个或多个保险库配置（请参见 多保险库配置)

1. 启动MCP服务器:

   npm run build && npm run start:http

1. 启用尾秤漏斗:

   tailscale funnel 3010

1. 获取您的公共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_AUTH_KEY进行MCP服务器身份验证，通过单个API密钥进行保险库身份验证
• 尾标加密：所有流量均由Tailscale端到端加密
• 专用网络：只有您可以通过Tailscale网络访问服务器
• 自动SSL：Tailscale漏斗提供自动HTTPS证书
• 保险库隔离：每个保险库都使用自己的API密钥进行安全访问控制

示例用法

设置后，您可以从Claude.ai远程使用工具：

单个vault命令（使用默认vault）：

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

多vault命令（指定vault）：

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漏斗自动启动，无需手动干预。

🤖 ChatGPT MCP层

克劳德直接连接到 /mcp，但ChatGPT的Actions工作流需要HTTP清单和REST风格的JSON端点。ChatGPT层封装了现有的MCP服务器，因此您可以重用所有传输、保险库路由和任务逻辑，而无需重复代码。

启用该层

1. 添加 CHATGPT_LAYER_ENABLED=true 根据您的环境（其他旋钮： CHATGPT_MANIFEST_PATH, CHATGPT_ACTIONS_PATH).
2. 重新启动服务器(npm run build && npm run start:http).
3. 获取清单以确认可用性：

   curl "http://127.0.0.1:3010/.well-known/obsidian-chatgpt-manifest.json"

清单通告MCP端点和单个JSON操作路由(/chatgpt/actions).两个端点重用相同的 MCP_AUTH_KEY 查询参数，因此您可以并行部署Tailscale/Claude和ChatGPT，而无需新的身份验证管道。

可用的ChatGPT操作

所有操作都接受可选 vault 字段（默认为第一个配置的vault）。请求是JSON格式的有效载荷：

POST /chatgpt/actions?api_key=YOUR_MCP_AUTH_KEY
{
  "action": "searchNotes",
  "vault": "work",
  "parameters": {
    "query": "project alpha",
    "searchInPath": "Projects/Alpha",
    "modified_since": "last week",
    "pageSize": 20
  }
}

响应包装现有的工具结果对象：

{
  "success": true,
  "action": "searchNotes",
  "vault": "work",
  "data": { "results": [...], "totalFilesFound": 5, "currentPage": 1, ... }
}

使用ChatGPT的Actions编辑器（或任何HTTP客户端）中的清单输出来描述可用功能，同时保持Claude/Tailscale流不变。

项目结构

代码库遵循模块化结构 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.

保险库缓存服务

此服务器包括一个智能 内存缓存 旨在增强与保险库交互时的性能和弹性。

目的和好处

• 演出：通过缓存文件内容和元数据，服务器可以更快地执行搜索操作，特别是在大型保管库中。这减少了对Obsidian本地REST API的直接请求数量，从而获得更快速的体验。
• 韧性：缓存充当 obsidian_global_search 工具。如果实时API搜索失败或超时，服务器将无缝使用缓存提供结果，从而确保即使Obsidian API暂时没有响应，搜索功能仍然可用。
• 效率：缓存的设计是高效的。它在启动时执行初始构建，然后通过检查文件修改在后台定期刷新，确保它保持合理的最新状态，而无需持续、大量的API轮询。

运作原理

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

配置

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

• OBSIDIAN_ENABLE_CACHE：设置为 true （默认）或 false 以启用或禁用缓存服务。
• OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN：定义定期背景刷新的间隔（以分钟为单位）。默认为 10.

工具

Obsidian MCP服务器提供了一套与您的保险库交互的工具，可通过模型上下文协议调用。

多保险库支持

所有工具都支持可选 vault 用于指定要对哪个vault进行操作的参数：

• 默认行为：没有 vault 参数，工具使用第一个配置的vault
• 特定保险库：添加 vault: "vault-id" 以特定保险库为目标
• 示例: obsidian_read_file(filePath="note.md", vault="work")

_注意：所有工具都支持全面的错误处理、多保险库路由和返回结构化JSON响应。_

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

归因

此叉子的增强功能：

• 多保险库支持：通过特定于保险库的路由同时访问多个黑曜石保险库
• Claude.ai远程MCP集成和兼容性修复
• Tailscale漏斗集成，实现安全远程访问
• 具有身份验证分离的增强HTTP传输层（MCP_AUTH_KEY）
• 使用Tasks插件集成进行高级任务查询
• 5个新的高级工具：定期注释、块参考、图形分析、模板系统和智能链接
• 企业使用的生产就绪配置

______________________________________________________________________

Built with the Model Context Protocol

Enhanced for Claude.ai Remote Integration