Obsidian MCP 服务器

一个为大型语言模型（LLMs）设计的与 Obsidian 知识库交互的模型上下文协议（MCP）服务器。使用 TypeScript 构建，具有安全的 API 通信、高效的文件操作和全面的搜索功能，使 AI 助手能够通过简洁灵活的工具界面无缝管理知识库。

模型上下文协议（MCP）使 AI 模型能够通过标准化接口与外部工具和资源进行交互。

需要在 Obsidian 中安装 Local REST API 插件。

📋 目录

功能 | 安装 | 配置 | 工具 | 资源 | 项目结构 | 贡献 | 发布 | 许可证

✨ 功能

文件操作：带有验证、资源监控和错误处理的原子文件/目录操作。
搜索系统：支持可配置上下文的高级全文搜索、JsonLogic 查询、glob 模式和 frontmatter 字段支持。
属性管理：YAML frontmatter 解析、智能合并、自动时间戳和自定义字段支持。
安全与性能：API 密钥认证、速率限制、SSL 选项、资源监控和优雅关闭。

🚀 安装

注意：需要 Node.js 和在 Obsidian 中启用 Local REST API 插件。

选项 1：克隆并构建（用于开发或直接使用）

在 Obsidian 中启用 Local REST API 插件。

克隆仓库，安装依赖并构建项目：

git clone git@github.com:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build

使用环境变量配置服务器（见下面的配置部分）。
配置你的 MCP 客户端设置（例如 claude_desktop_config.json 或 cline_mcp_settings.json）以包含服务器。详情请见配置部分。

选项 2：通过 npm 安装（作为依赖项或全局安装）

在 Obsidian 中启用 Local REST API 插件。

使用 npm 安装包：

# 本地安装（例如在另一个项目中）
npm install obsidian-mcp-server

# 或者全局安装
npm install -g obsidian-mcp-server

配置你的 MCP 客户端设置（例如 claude_desktop_config.json 或 cline_mcp_settings.json）以包含服务器。详情请见配置部分。

⚙️ 配置

将以下内容添加到你的 MCP 客户端设置中（例如 claude_desktop_config.json 或 cline_mcp_settings.json）：

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

环境变量：

OBSIDIAN_API_KEY（必需）：来自 Obsidian 的 Local REST API 插件设置的 API 密钥。
VERIFY_SSL（默认：false）：启用 SSL 验证。对于自签名证书或本地使用，设置为 false。
OBSIDIAN_PROTOCOL（默认："https"）：协议（http 或 https）。
OBSIDIAN_HOST（默认："127.0.0.1"）：主机地址。
OBSIDIAN_PORT（默认：27124）：端口号。
REQUEST_TIMEOUT（默认：5000）：请求超时（毫秒）。
MAX_CONTENT_LENGTH（默认：52428800 [50MB]）：最大响应内容长度（字节）。
MAX_BODY_LENGTH（默认：52428800 [50MB]）：最大请求体长度（字节）。
RATE_LIMIT_WINDOW_MS（默认：900000 [15 分钟]）：速率限制窗口（毫秒）。
RATE_LIMIT_MAX_REQUESTS（默认：200）：每个窗口的最大请求数。
TOOL_TIMEOUT_MS（默认：60000 [1 分钟]）：工具执行超时（毫秒）。

🛠️ 工具

工具	描述	参数
obsidian_list_files_in_vault	列出 Obsidian 知识库根目录下的所有文件和目录。返回一个层次结构，详细说明文件、文件夹及其类型。	无
obsidian_list_files_in_dir	列出 Obsidian 知识库中特定文件夹中的文件和目录。返回一个层次结构。注意：空目录可能不会包含在结果中。适用于探索知识库组织。	`dirpath*`：要列出文件的路径（相对于知识库根目录）。注意，空目录不会返回。
obsidian_get_file_contents	检索 Obsidian 知识库中指定文件的完整内容。支持各种可读文件格式。	`filepath*`：相关文件的路径（相对于你的知识库根目录）。
obsidian_append_content	将提供的内容追加到知识库中指定文件的末尾。如果文件不存在，将会创建它。	`filepath`：文件的路径（相对于知识库根目录） `content`：要追加到文件的内容
obsidian_update_content	用提供的内容覆盖知识库中指定文件的全部内容。如果文件不存在，将会创建它。	`filepath`：文件的路径（相对于知识库根目录） `content`：文件的新完整内容（覆盖现有内容）。
obsidian_find_in_file	在 Obsidian 知识库中的所有文件中执行全文搜索。返回匹配的文件及其上下文。如果超过 5 个文件匹配，则只返回文件名和匹配计数，以避免输出过多。适用于查找特定文本、标签或模式。	`query*`：要搜索的文本模式。可以包括标签、关键词或短语。 `contextLength`：围绕每个匹配项提供上下文的字符数（默认：10）。
obsidian_complex_search	使用 JsonLogic 查询基于路径模式查找文件。主要支持 `glob` 进行模式匹配（例如 '*.md'）和 `var` 访问 'path' 变量。注意：对于基于内容的搜索（全文、内容中的标签、日期），请使用 `obsidian_find_in_file`。	`query`：针对文件路径的 JsonLogic 查询对象。示例：`{"glob": [".md", {"var": "path"}]}` 匹配所有 markdown 文件。
obsidian_get_tags	检索 Obsidian 知识库中 markdown 文件的 YAML frontmatter 中定义的所有标签，及其使用次数和关联的文件路径。可选地，将搜索限制在特定文件夹中。	`path`：可选文件夹路径（相对于知识库根目录）以限制标签搜索。
obsidian_get_properties	从指定的 Obsidian 笔记的 YAML frontmatter 中检索属性（如标题、标签、状态）。返回所有定义的属性，包括任何自定义字段。	`filepath*`：笔记文件的路径（相对于知识库根目录）
obsidian_update_properties	更新指定的 Obsidian 笔记的 YAML frontmatter 中的属性。默认情况下，数组属性（如标签、类型、状态）会合并；使用 'replace' 选项可以覆盖它们。处理自定义字段并自动管理时间戳。参见模式以了解支持的标准字段（标题、作者、标签、状态等）。	`filepath`：笔记文件的路径（相对于知识库根目录） `properties`：要更新的属性 `replace`：如果为 true，数组属性（如标签、状态）将完全替换为提供的值，而不是与现有值合并。默认为 false（合并）。

🔗 资源

资源	描述	返回
obsidian://tags	Obsidian 知识库中使用的所有标签及其使用次数的列表	application/json

📁 项目结构

该项目采用模块化架构，职责明确：

src/
  ├── index.ts          # 主入口点
  ├── mcp/              # MCP 服务器实现
  ├── obsidian/         # Obsidian API 客户端和类型
  ├── resources/        # MCP 资源实现
  ├── tools/            # MCP 工具实现
  │   ├── files/        # 文件操作工具
  │   ├── search/       # 搜索工具
  │   └── properties/   # 属性管理工具
  └── utils/            # 共享工具

👥 贡献

分叉仓库
创建功能分支
提交 Pull Request

对于错误和功能，请在 https://github.com/cyanheads/obsidian-mcp-server/issues 创建问题。

📄 许可证

Apache 许可证 2.0

基于模型上下文协议构建