Obsidian MCP 服务器

一个为 LLM 设计的 Model Context Protocol 服务器，用于与 Obsidian vault 交互。它使用 TypeScript 构建，具有安全的 API 通信、高效的文件操作和全面的搜索功能，使 AI 助手能够通过一个干净、灵活的工具界面无缝地管理知识库。

Model Context Protocol (MCP) 使 AI 模型能够通过标准化接口与外部工具和资源进行交互。

需要在 Obsidian 中启用 Local REST API 插件。

功能

文件操作

• 具有验证功能的原子文件/目录操作
• 资源监控和清理
• 错误处理和优雅失败

搜索系统

• 具有可配置上下文的全文本搜索
• 用于文件、标签和元数据的高级 JsonLogic 查询
• 支持 glob 模式和 frontmatter 字段

属性管理

• YAML frontmatter 解析和智能合并
• 自动时间戳（由 Obsidian 创建，由服务器修改）
• 自定义字段支持

安全性与性能

• 具有速率限制和 SSL 选项的 API 密钥身份验证
• 资源监控和健康检查
• 优雅的关闭处理

安装

注意：需要 Node.js

1. 在 Obsidian 中启用 Local REST API 插件
2. 克隆并构建：

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

或者从 npm 安装：

npm install obsidian-mcp-server

配置

添加到您的 MCP 客户端设置（例如，claude_desktop_config.json 或 cline_mcp_settings.json）：

{
  "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"
      }
    }
  }
}

环境变量：

必需：

• OBSIDIAN_API_KEY: 来自 Obsidian 的 Local REST API 插件设置的 API 密钥

连接设置：

• VERIFY_SSL: 启用 SSL 证书验证（默认：false）# 对于自签名证书，必须将其设置为 false。如果您在本地运行或不明白这意味着什么，则应将其设置为 false。
• OBSIDIAN_PROTOCOL: 使用的协议（默认："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 分钟]）

项目结构

该项目遵循模块化架构，具有清晰的关注点分离：

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

工具

文件管理

// 列出 vault 内容
obsidian_list_files_in_vault: {
}

// 列出目录内容
obsidian_list_files_in_dir: {
  dirpath: string; // 相对于 vault 根目录的路径
}

// 获取文件内容
obsidian_get_file_contents: {
  filepath: string; // 相对于 vault 根目录的路径
}

搜索操作

// 具有上下文的文本搜索
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // 默认值：10
}

// 使用 JsonLogic 的高级搜索
obsidian_complex_search: {
  query: JsonLogicQuery
  // 示例：
  // 按标签查找：
  // {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  //
  // 在目录中查找 markdown 文件：
  // {"glob": ["docs/*.md", {"var": "path"}]}
  //
  // 组合条件：
  // {"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}
}

// 获取 vault 或目录中的所有标签
obsidian_get_tags: {
  path?: string  // 可选：限制为特定目录
}

内容修改

// 追加到文件
obsidian_append_content: {
  filepath: string,  // 相对于 vault 根目录的路径
  content: string    // 要追加的内容
}

// 更新文件内容
obsidian_patch_content: {
  filepath: string,  // 相对于 vault 根目录的路径
  content: string    // 新内容（替换现有内容）
}

属性管理

// 获取笔记属性
obsidian_get_properties: {
  filepath: string  // 相对于 vault 根目录的路径
}

// 更新笔记属性
obsidian_update_properties: {
  filepath: string,  // 相对于 vault 根目录的路径
  properties: {
    title?: string,
    author?: string,
    // 注意：创建/修改时间戳是自动管理的
    type?: Array<"concept" | "architecture" | "specification" |
      "protocol" | "api" | "research" | "implementation" |
      "guide" | "reference">,
    tags?: string[],  // 必须以 # 开头
    status?: Array<"draft" | "in-progress" | "review" | "complete">,
    version?: string,
    platform?: string,
    repository?: string,  // URL
    dependencies?: string[],
    sources?: string[],
    urls?: string[],      // URLs
    papers?: string[],
    custom?: Record<string, unknown>
  }
}

最佳实践

文件操作

• 使用具有验证功能的原子操作
• 处理错误并监控性能

搜索实现

• 为任务使用适当的搜索工具：
  • obsidian_find_in_file 用于文本搜索
  • obsidian_complex_search 用于元数据/标签过滤
• 保持上下文大小合理（默认值：10 个字符）

属性管理

• 使用适当的类型并验证更新
• 正确处理数组和自定义字段
• 永远不要设置时间戳（自动管理）

错误预防

• 验证输入并优雅地处理错误
• 监控模式并遵守速率限制

资源

MCP 服务器公开以下资源：

obsidian://tags  # vault 中使用的所有标签的列表

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交 Pull Request

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

发布

当推送版本标签时，该软件包会自动发布到 npm：

# 更新 package.json 中的版本
npm version patch  # 或 minor，或 major
git push --follow-tags

这将触发 GitHub Action 来构建和发布该软件包。

许可证

Apache License 2.0

---

<div align="center"> 使用 Model Context Protocol 构建 </div>