AI导哈

Obsidian MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，使AI助手能够通过复杂的双访问架构与您的Obsidian库交互。

  • by Beaulewis1977
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Beaulewis1977/obsidian-mcp

使用说明

黑曜石MCP服务器

🤖 AI驱动的黑曜石集成|🚀 生产就绪|📚 知识管理

👨‍💻 关于开发者

由Beau Lewis设计和制造
📧 blewisxx@gmail.com

“我喜欢创建帮助人们的开源项目。如果这个项目对你有帮助，你想帮助这项事业，请去做！”

Support My Work:
Venmo: @beauintulsa | Ko‑fi: ko-fi.com/beaulewis
Repo: github.com/Beaulewis1977/obsidian-mcp

🌟 什么是黑曜石MCP服务器？

A. 生产就绪模型上下文协议（MCP）服务器 它使AI助手（Claude、ChatGPT等）能够通过复杂的双访问架构与您的黑曜石金库进行交互。

把它想象成一座桥 在你的人工智能助手和黑曜石的个人知识库之间，让人工智能无缝地阅读、写作、搜索和组织你的笔记。

🎯 关键利益

  • 🔍 智能搜索：AI可以立即找到并分析您的笔记
  • ✍️ 内容创作：生成格式正确的新笔记
  • 🔗 知识发现：寻找想法之间的联系
  • 📊 保险库分析：了解你的知识库结构
  • 🤖 AI工作流集成：使用人工智能来增强你的PKM系统

🏗️ 建筑亮点

  • 双重访问模式：黑名单REST API（主）+文件系统（回退）
  • 交叉平台的：Windows本机和WSL支持
  • 速率限制：可配置的限制，具有优雅的降级
  • 文件监视：实时保险库更改检测
  • 安全第一：路径验证、API密钥保护、错误处理

✨ 特性

🔧 13种强大的工具可供选择

核心业务 📝

  • read_note -阅读包含完整元数据、正文和内容的笔记
  • create_note -使用YAML frontmatter创建新笔记
  • edit_note -使用多种模式修改注释（追加、预置、替换、基于标题）
  • delete_note -确认后删除笔记

搜索与发现 🔍

  • list_notes -使用筛选（文件夹、标记、日期、模式）浏览vault
  • search_notes -通过Obsidian API或文件系统进行全文搜索
  • get_backlinks -查找链接到特定笔记的所有笔记
  • get_vault_stats -保险库分析（计数、标签、链接、大小）

组织 📁

  • move_note -移动/重命名笔记（带有链接更新警告）
  • update_frontmatter -在不接触内容的情况下修改元数据
  • create_folder -在vault结构中创建新文件夹

高级功能 ⚡

  • get_daily_note -具有可配置日期格式的每日笔记
  • open_in_obsidian -直接在Obsidian应用程序中打开笔记

🛡️ 企业级功能

安全性和可靠性

  • 路径验证：防止目录遍历攻击
  • API密钥保护：安全的凭证处理
  • 错误恢复：当API失败时，优雅地回退到文件系统
  • 速率限制：多层限制（全局、每个操作、每个工具）
  • 请求排队：优雅地处理流量峰值

性能和可扩展性

  • 文件监视：实时保险库更改检测
  • 智能缓存：针对大型保险库进行了优化
  • 交叉平台的：Windows原生+WSL支持
  • 连接池：高效使用API

开发者体验

  • TypeScript：全程全型安全
  • 综合测试：78次测试，覆盖率超过80%
  • CI/CD管道：自动质量门
  • CodeRabbit集成：AI驱动的代码审查

🚀 快速开始

先决条件

  • Node.js 18+ (下载)
  • 黑曜石 随着 本地REST API 插件已启用
  • API密钥 来自黑曜石（设置→ 社区插件→ 本地REST API）

安装和设置

# 1. Clone the repository
git clone https://github.com/Beaulewis1977/obsidian-mcp.git
cd obsidian-mcp

# 2. Install dependencies
npm install

# 3. Create your configuration file (see below)
#    Save as %USERPROFILE%/.obsidian-mcp/config.json (Windows)
#    or ~/.obsidian-mcp/config.json (macOS/Linux)
#    Alternatively, set CONFIG_PATH to point to your config file.

# 4. Build the project
npm run build

# 5. Start the server
node dist/index.js
# Or with a helper that prints guidance if not yet built:
# node start-server.mjs

配置

此服务器是通过JSON文件配置的。环境变量可以补充设置，但不能取代定义Vault的需要。

服务器在哪里查找配置

  • CONFIG_PATH 环境变量（如果设置）
  • %USERPROFILE%/.obsidian-mcp/config.json （Windows）或 ~/.obsidian-mcp/config.json
  • ./config.json （当前工作目录）
  • ../config.json （父目录）

最小配置示例

{
  "version": "1.0",
  "vaults": [
    {
      "name": "main",
      "path": "/path/to/your/vault",
      "default": true,
      "obsidian_api": {
        "enabled": true,
        "url": "http://127.0.0.1:27123",
        "verify_ssl": false,
        "api_key": "${OBSIDIAN_API_KEY}",
        "timeout": 5000,
        "retry": { "enabled": true, "max_retries": 2, "initial_delay": 1000, "max_delay": 10000 },
        "fallback_to_filesystem": true
      },
      "daily_notes": { "folder": "daily", "date_format": "YYYY-MM-DD", "template": null }
    }
  ]
}

扩展配置（速率限制、文件监视、限制、功能）

{
  "version": "1.0",
  "vaults": [ { "name": "main", "path": "/path/to/your/vault", "default": true, "obsidian_api": { "enabled": true, "url": "http://127.0.0.1:27123", "verify_ssl": false, "api_key": "${OBSIDIAN_API_KEY}", "timeout": 5000, "retry": { "enabled": true, "max_retries": 2, "initial_delay": 1000, "max_delay": 10000 }, "fallback_to_filesystem": true }, "daily_notes": { "folder": "daily", "date_format": "YYYY-MM-DD", "template": null } } ],
  "rate_limiting": {
    "enabled": true,
    "limits": {
      "global": { "requests_per_minute": 1000, "requests_per_hour": 10000 },
      "read": { "requests_per_minute": 600, "requests_per_hour": 6000 },
      "write": { "requests_per_minute": 100, "requests_per_hour": 1000 },
      "tools": {
        "edit_note": { "requests_per_minute": 30 },
        "delete_note": { "requests_per_minute": 20 },
        "move_note": { "requests_per_minute": 25 },
        "search_notes": { "requests_per_minute": 60 },
        "get_backlinks": { "requests_per_minute": 100 }
      }
    },
    "graceful": { "warn_at_percentage": 80, "queue_requests": false, "max_queue_size": 100, "queue_timeout_ms": 30000 }
  },
  "file_watching": { "enabled": true, "polling": { "interval": 1000, "binary_interval": 2000 }, "stability_threshold": 2000 },
  "limits": { "max_file_size": 10485760, "warning_threshold": 1048576 },
  "features": { "backup_on_delete": false, "advisory_locking": false }
}

有用的环境变量

  • CONFIG_PATH：配置JSON的绝对路径。
  • OBSIDIAN_API_KEY：在以下情况下使用 obsidian_api.api_key 设置为 ${OBSIDIAN_API_KEY}.
  • LOG_LEVEL：其中之一 trace|debug|info|warn|error|fatal.
  • RATE_LIMITING_*, FILE_WATCHING_ENABLED：可选切换；看见 .env.example.

AI助手集成

克劳德桌面版

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"]
    }
  }
}

其他MCP兼容工具

该服务器实现了完整的MCP协议，并可与任何兼容MCP的AI助手配合使用。

📚 文档

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发流程

  1. 分叉 存储库
  2. 创建 一个特征分支 develop
  3. 制造 您通过测试所做的更改
  4. 测试 彻底(npm run lint && npm run test)
  5. 提交 拉取请求 develop
  6. CodeRabbit 将自动审核
  7. 合并 批准后

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

内置于❤️ 黑曜石和MCP社区。

⭐ If this project helps you, please consider starring the repository!

相关 MCP