Obsidian MCP Server 使用说明

项目简介

Obsidian MCP Server 是一个 Model Context Protocol (MCP) 服务器，专为连接大型语言模型（LLMs）和 Obsidian 知识库而设计。它充当 LLM 与您的本地 Obsidian 笔记库之间的桥梁，使 AI 助手能够以标准化和安全的方式访问、搜索、修改您的笔记内容和元数据。通过此服务器，您可以构建更智能的 AI 应用，例如：

智能笔记助手: 让 LLM 总结笔记、查找信息、辅助内容创作。
知识库管理: 使用 LLM 批量管理和更新笔记的标签、属性等元数据。
自动化工作流: 结合 LLM 和笔记内容，实现自动化任务和信息处理流程。

主要功能点

文件操作: 提供原子性的文件和目录操作，支持资源监控和清理，确保数据一致性和稳定性。
强大的搜索系统: 支持全文搜索、JsonLogic 高级查询（基于文件、标签、元数据）、Glob 模式匹配和 Frontmatter 字段搜索，满足各种复杂的检索需求。
属性管理: 智能解析和合并 YAML Frontmatter，自动管理时间戳（创建和修改时间），支持自定义字段，方便笔记元数据管理。
安全与性能: 采用 API 密钥认证、速率限制和 SSL 加密选项，保障 API 通信安全；具备资源监控和健康检查机制，确保服务器稳定运行。

安装步骤

前提条件:

已安装 Obsidian 软件
已在 Obsidian 中安装并启用 Local REST API 插件
已安装 Node.js 环境

安装方式一：从 npm 安装 (推荐)

打开终端，运行以下命令安装 'obsidian-mcp-server' 包：

npm install obsidian-mcp-server

安装方式二：从 GitHub 仓库克隆并构建

打开终端，克隆 GitHub 仓库到本地：

git clone [email protected]:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server

安装依赖并构建项目：

npm install
npm run build

服务器配置

MCP 服务器需要配置在 MCP 客户端中。以下是一个示例配置，您需要根据实际安装路径进行调整。

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/build/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"
      }
    }
  }
}

配置参数说明 (请根据您的环境修改以下参数):

'command': 启动 Obsidian MCP Server 的命令，通常为 'node'。
'args': 启动命令的参数，指向 'obsidian-mcp-server' 构建后的入口文件 'index.js' 的绝对路径。 请将 '/path/to/obsidian-mcp-server/build/index.js' 替换为您实际的安装路径。
'env': 环境变量配置，包含以下参数：
- 'OBSIDIAN_API_KEY': 必填。您在 Obsidian 的 Local REST API 插件设置中生成的 API Key，用于服务器认证。请将 'your_api_key_here' 替换为您实际的 API Key。
- 'VERIFY_SSL': 是否启用 SSL 证书验证。本地开发或自签名证书场景建议设置为 '"false"'。生产环境建议配置 HTTPS 并设置为 '"true"'。
- 'OBSIDIAN_PROTOCOL': Obsidian Local REST API 使用的协议，默认为 '"https"'。如果 Obsidian 插件配置为 HTTP，请修改为 '"http"'。
- 'OBSIDIAN_HOST': Obsidian Local REST API 的主机地址，默认为 '"127.0.0.1"' (本地)。
- 'OBSIDIAN_PORT': Obsidian Local REST API 的端口号，默认为 '"27124"'。
- 'REQUEST_TIMEOUT': 请求超时时间，单位毫秒，默认为 '"5000"' (5秒)。
- '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"' (60秒)。

请注意: 确保您已在 Obsidian 中启用 Local REST API 插件并配置好 API Key。

基本使用方法

启动 Obsidian MCP Server:
- 如果您是 npm 安装，通常 MCP 客户端会自动启动服务器。
- 如果您是克隆仓库构建，您可能需要手动运行 'node build/index.js' 或使用 'npm start' 命令启动服务器。
配置 MCP 客户端:
- 根据您的 MCP 客户端 (例如 Claude 桌面版、Cline 等) 的文档，将上述服务器配置信息添加到客户端的配置文件中 (例如 'claude_desktop_config.json' 或 'cline_mcp_settings.json')。
使用 LLM 客户端与 Obsidian 互动:
- 客户端连接到 Obsidian MCP Server 后，您可以使用 LLM 客户端提供的工具 (Tools) 和资源 (Resources) 与您的 Obsidian 知识库进行交互。
- 例如，您可以让 LLM 使用 'obsidian_find_in_file' 工具搜索笔记内容，或使用 'obsidian_get_properties' 工具获取笔记属性。
- 具体工具和资源的使用方法请参考仓库 README.md 文档中 "Tools" 和 "Resources" 章节的详细说明。

示例工具 (Tools):

'obsidian_list_files_in_vault': 列出 Obsidian Vault 根目录下的所有文件和文件夹。
'obsidian_get_file_contents': 获取指定路径笔记文件的内容。
'obsidian_find_in_file': 在整个 Obsidian Vault 中搜索包含特定关键词的笔记。
'obsidian_update_properties': 更新指定笔记文件的 Frontmatter 属性 (例如标签、标题等)。

示例资源 (Resources):

'obsidian://tags': 获取 Obsidian Vault 中所有标签及其使用情况的列表。

通过这些工具和资源，您可以构建强大的 AI 应用，充分利用您的 Obsidian 知识库。

关键词