黑曜石-MCP服务器

Name: 黑曜石-MCP服务器
Author: cyanheads

作者：cyanheads290 星标更新：2025-10-25

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Obsidian MCP Server

通过无缝集成Obsidian来增强您的AI代理和开发工具！

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

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

🚀 核心能力：Obsidian工具 🛠️

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

工具名称	描述	关键特性
`obsidian_read_note`	检索指定笔记的内容和元数据。	- 以`markdown`或`json`格式读取。<br/>- 支持大小写不敏感路径回退。<br/>- 包括文件状态（创建/修改时间）。
`obsidian_update_note`	使用整个文件操作修改笔记。	- 可以追加、前置或覆盖内容。<br/>- 如果文件不存在，可以创建文件。<br/>- 通过路径、活动笔记或周期性笔记定位文件。
`obsidian_search_replace`	在目标笔记中执行查找和替换操作。	- 支持字符串或正则表达式搜索。<br/>- 提供大小写敏感、全词匹配和替换所有出现的选项。
`obsidian_global_search`	在整个保险库中执行搜索。	- 文本或正则表达式搜索。<br/>- 根据路径和修改日期过滤。<br/>- 分页结果。
`obsidian_list_notes`	列出指定保险库文件夹中的笔记和子目录。	- 根据文件扩展名或名称正则表达式过滤。<br/>- 提供格式化的目录树视图。
`obsidian_manage_frontmatter`	原子地管理笔记的YAML前缀。	- 获取、设置或删除前缀键。<br/>- 避免为了元数据更改而重写整个文件。
`obsidian_manage_tags`	为笔记添加、移除或列出标签。	- 管理YAML前缀和内联内容中的标签。
`obsidian_delete_note`	永久从保险库中删除指定的笔记。	- 为安全起见，支持大小写不敏感路径回退。

概述

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

无需复杂的脚本或手动交互，您的工具可以通过此服务器实现以下功能：

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

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

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

功能

核心实用工具

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

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

Obsidian集成

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

安装

先决条件

Obsidian：您需要安装Obsidian。
Obsidian本地REST API插件：在您的Obsidian保险库中安装并启用Obsidian本地REST API插件。
API密钥：在Obsidian的本地REST API插件设置中配置API密钥。您需要此密钥来配置服务器。
Node.js & npm：确保您已安装Node.js（推荐版本18或更高）和npm。

配置

MCP客户端设置

将以下内容添加到您的MCP客户端配置文件（例如，cline_mcp_settings.json）。此配置使用npx运行服务器，如果尚未存在，它将自动下载并安装包：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

注意：这里将SSL验证设置为false，因为Obsidian本地REST API插件默认使用自签名证书。如果您在生产环境中部署此服务，请考虑使用加密的HTTPS端点，并在配置服务器信任自签名证书后将OBSIDIAN_VERIFY_SSL设置为true。

如果您是从源代码安装的，请更改command和args指向您的本地构建：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "YOUR_OBSIDIAN_API_KEY",
        "OBSIDIAN_BASE_URL": "http://127..0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

环境变量

使用环境变量配置服务器。这些环境变量设置在您的MCP客户端配置/设置中（例如，对于Cline是cline_mcp_settings.json，对于Claude Desktop是claude_desktop_config.json）。

变量	描述	必需	默认值
`OBSIDIAN_API_KEY`	来自Obsidian本地REST API插件的API密钥。	是	`undefined`
`OBSIDIAN_BASE_URL`	您的Obsidian本地REST API的基本URL。	是	`http://127.0.0.1:27123`
`MCP_TRANSPORT_TYPE`	服务器传输：`stdio`或`http`。	否	`stdio`
`MCP_HTTP_PORT`	HTTP服务器的端口。	否	`3010`
`MCP_HTTP_HOST`	HTTP服务器的主机。	否	`127.0.0.1`
`MCP_ALLOWED_ORIGINS`	CORS的逗号分隔来源。用于生产环境。	否	（无）
`MCP_AUTH_MODE`	身份验证策略：`jwt`或`oauth`。	否	（无）
`MCP_AUTH_SECRET_KEY`	用于JWT的32个字符以上的密钥。在`jwt`模式下需要。	是（如果`jwt`）	`undefined`
`OAUTH_ISSUER_URL`	OAuth 2.1发行者的URL。	是（如果`oauth`）	`undefined`
`OAUTH_AUDIENCE`	OAuth令牌的受众声明。	是（如果`oauth`）	`undefined`
`OAUTH_JWKS_URI`	JSON Web Key Set的URI（可选，如果省略则从发行人派生）。	否	（派生）
`MCP_LOG_LEVEL`	日志级别（`debug`、`info`、`error`等）。	否	`info`
`OBSIDIAN_VERIFY_SSL`	设置为`false`以禁用SSL验证。	否	`true`
`OBSIDIAN_ENABLE_CACHE`	设置为`true`以启用内存中的保险库缓存。	否	`true`
`OBSIDIAN_CACHE_REFRESH_INTERVAL_MIN`	保险库缓存的刷新间隔（分钟）。	否	`10`

连接到Obsidian API

要将MCP服务器连接到您的Obsidian保险库，您需要配置基本URL（OBSIDIAN_BASE_URL）和API密钥（OBSIDIAN_API_KEY）。Obsidian本地REST API插件提供了两种连接方式：

加密（HTTPS）- 默认：
- 插件提供了一个安全的https://端点（例如，https://127.0.0.1:27124）。
- 这使用了自签名证书，默认情况下会导致连接错误。
- 要解决这个问题，您必须将OBSIDIAN_VERIFY_SSL环境变量设置为"false"。这告诉服务器信任自签名证书。
非加密（HTTP）- 推荐用于简单性：
- 在Obsidian中的插件设置中，您可以启用“非加密（HTTP）服务器”。
- 这提供了一个更简单的http://端点（例如，http://127.0.0.1:27123）。
- 使用这个URL时，您不需要担心SSL验证。

示例env配置用于您的MCP客户端：

使用非加密的HTTP URL（推荐）：

"env": {
  "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
  "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123"
}

使用加密的HTTPS URL：

"env": {
  "OBSIDIAN_API_KEY": "YOUR_API_KEY_FROM_OBSIDIAN_PLUGIN",
  "OBSIDIAN_BASE_URL": "https://127.0.0.1:27124",
  "OBSIDIAN_VERIFY_SSL": "false"
}

项目结构

代码库在src/目录中遵循模块化结构：

src/
├── index.ts           # 入口点：初始化并启动服务器
├── config/            # 配置加载（环境变量，包信息）
│   └── index.ts
├── mcp-server/        # 核心MCP服务器逻辑和功能注册
│   ├── server.ts      # 服务器设置，传输处理，工具/资源注册
│   ├── resources/     # MCP资源实现（目前没有）
│   ├── tools/         # MCP工具实现（每个工具的子目录）
│   └── transports/    # Stdio和HTTP传输逻辑
│       └── auth/      # 身份验证策略（JWT，OAuth）
├── services/          # 外部API或内部缓存的抽象
│   └── obsidianRestAPI/ # Obsidian本地REST API的类型客户端
├── types-global/      # 共享的TypeScript类型定义（错误等）
└── utils/             # 常用工具函数（日志记录器，错误处理器，安全等）

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

保险库缓存服务

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

目的和好处

性能：通过缓存文件内容和元数据，服务器可以在大型保险库中更快地执行搜索操作。这减少了直接请求到Obsidian本地REST API的数量，从而带来了更流畅的体验。
弹性：缓存作为obsidian_global_search工具的回退。如果实时API搜索失败或超时，服务器无缝地使用缓存提供结果，即使Obsidian API暂时不可用，搜索功能仍然可用。
效率：缓存设计为高效。它在启动时构建内存映射，并在后台定期刷新，检查文件修改，确保它保持合理更新而不进行持续、沉重的API轮询。

工作原理

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

配置

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

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

工具

Obsidian MCP Server提供了一系列工具，用于与您的保险库进行交互，这些工具可以通过模型上下文协议调用。

工具名称	描述	关键参数
`obsidian_read_note`	检索笔记的内容和元数据。