Obsidian笔记AI集成服务

麦克。黑曜石

麦克。黑曜石 是a。NET 10模型上下文协议（MCP）服务器，将AI代理（Claude、Gemini、Cursor等）与本地黑曜石保险库连接起来。

它允许LLM使用 黑名单本地REST API，首先将您的知识库保持在本地，同时实现人工智能自动化。

这个33工具服务器的设计感觉更接近于一个真正的黑曜石操作员，而不是一个薄薄的CRUD包装器。它可以处理正常的vault文件、活动注释、定期注释、命令执行、vault查询、反向链接感知分析、工作区脚手架、看板和MCP资源。

是什么让它与众不同

• 它不仅限于文件CRUD。它可以推理标题、链接、反向链接、定期注释和黑曜石命令。
• 它公开了更高级的代理工作流，如智能追加、日常笔记自动化和工作空间脚手架。
• 它支持Obsidian REST模式和直接文件系统模式，用于离线vault访问。
• 它通过stdio和HTTP/SSE传输MCP，因此更多的MCP客户端可以干净地连接。
• 它将vault笔记作为MCP资源公开，而不仅仅是工具。

为什么这很有用

• 将笔记保存在本地，同时仍让兼容MCP的客户端使用它们。
• 允许Claude Desktop、Cursor、Gemini和其他MCP工具结构化访问您的黑曜石保险库。
• 通过让代理直接搜索、阅读、创建和更新笔记，避免脆弱的复制粘贴工作流程。
• 建立在广泛使用的Obsidian本地REST API之上，而不是发明一个自定义插件。
• 涵盖更高层次的工作流程，如日常笔记、标题感知附加、命令执行、看板解析和工作区引导。

[！注意] 演示图像尚未包含在此存储库中，因此占位符标题暂时已被删除。 一旦存在真实的记录，请将其添加回类似的内容 ![Demo](docs/demo.gif).

🏗 建筑

graph LR
    A[User] -->|Prompts| B[AI Client<br>Claude Desktop / Gemini]
    B <-->|MCP Protocol| C[Mcp.Obsidian Server<br>.NET 10]
    C <-->|HTTPS / Localhost| D[Obsidian Plugin<br>Local REST API]
    D -->|Read/Write| E[(Obsidian Vault)]

🚀 入门指南

✨ 选择你的模式

• REST mode：在Obsidian运行时通过Obsidian本地REST API插件连接。
• Filesystem mode：将服务器指向vault文件夹 --vault-path=/absolute/path/to/vault 在没有黑曜石跑步的情况下工作。
• HTTP mode：添加 --http-port=7474 暴露MCP http://localhost:7474/mcp SSE在 http://localhost:7474/sse.

1.先决条件

您将需要：

• 黑曜石桌面
• .NET 10 SDK
• 黑名单本地REST API 社区插件by coddingtonbear

安装并启用黑曜石插件：

1. 打开黑曜石。
2. 首选 Settings → Community plugins.
3. 安装并启用 Local REST API.
4. 打开插件设置。
5. 复制API密钥。

2.安装二进制文件或从源代码构建

选项A：下载预构建版本

转到GitHub发布页面并下载适用于您平台的存档：

• Mcp.Obsidian-linux-x64.tar.gz
• Mcp.Obsidian-linux-arm64.tar.gz
• Mcp.Obsidian-win-x64.zip
• Mcp.Obsidian-osx-arm64.tar.gz

在机器上的任何地方打开它，然后创建一个 appsettings.json 文件旁边的二进制文件或提供等效的环境变量。

选项B：从源代码构建

克隆存储库并创建本地配置：

git clone https://github.com/yourusername/Mcp.Obsidian.git
cd Mcp.Obsidian
cp appsettings.json.example appsettings.json

更新 appsettings.json 在repo根目录中显示您的黑曜石连接详细信息：

{
  "Obsidian": {
    "BaseUrl": "https://127.0.0.1:27124",
    "ApiKey": "YOUR_OBSIDIAN_API_KEY_HERE",
    "VerifySsl": false
  }
}

对于文件系统模式，您不需要API密钥：

dotnet run --project src/Mcp.Obsidian/Mcp.Obsidian.csproj -- --vault-path=/absolute/path/to/vault

您还可以通过环境变量配置服务器：

export OBSIDIAN__BASEURL=https://127.0.0.1:27124
export OBSIDIAN__APIKEY=YOUR_OBSIDIAN_API_KEY_HERE
export OBSIDIAN__VERIFYSSL=false

3.在本地构建或发布

构建MCP服务器：

dotnet build src/Mcp.Obsidian/Mcp.Obsidian.csproj

为当前计算机发布独立文件夹：

dotnet publish src/Mcp.Obsidian/Mcp.Obsidian.csproj -c Release -o ./artifacts/obsidian-mcp

为特定平台发布单个文件二进制文件：

dotnet publish src/Mcp.Obsidian/Mcp.Obsidian.csproj \
  -c Release \
  -r linux-x64 \
  -p:PublishSingleFile=true \
  -p:SelfContained=true \
  -o ./artifacts/linux-x64

在禁用ONNX语义搜索的情况下发布NativeAOT二进制文件：

dotnet publish src/Mcp.Obsidian/Mcp.Obsidian.csproj \
  -c Release \
  -r osx-arm64 \
  -p:AOT=true

4.将其连接到您的MCP客户端

服务器使用MCP stdio传输，因此任何可以启动本地命令的MCP兼容工具都可以使用它。

克劳德桌面

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/Mcp.Obsidian/src/Mcp.Obsidian/Mcp.Obsidian.csproj",
        "--",
        "--config=/absolute/path/to/Mcp.Obsidian/appsettings.json"
      ]
    }
  }
}

通用MCP客户端

如果您的MCP客户端更喜欢构建的可执行文件，请将其指向已发布的二进制文件：

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/Mcp.Obsidian/artifacts/obsidian-mcp/Mcp.Obsidian",
      "args": []
    }
  }
}

Windows示例：

{
  "mcpServers": {
    "obsidian": {
      "command": "C:\\absolute\\path\\to\\Mcp.Obsidian.exe",
      "args": []
    }
  }
}

HTTP MCP客户端

使用HTTP端口启动服务器：

dotnet run --project src/Mcp.Obsidian/Mcp.Obsidian.csproj -- --http-port=7474

然后将MCP请求发送到 http://localhost:7474/mcp.

5.快速入门检查表

1. 启动黑曜石并确保 Local REST API 插件已启用。
2. 确认您的API密钥存在于 appsettings.json 或环境变量。
3. 下载发布资产或运行 dotnet build src/Mcp.Obsidian/Mcp.Obsidian.csproj.
4. 将MCP服务器条目添加到您的客户端配置中。
5. 重新启动MCP客户端。
6. 请客户致电 obsidian_list_files 或 obsidian_search 作为烟雾测试。
7. 如果您的客户支持MCP资源，请尝试 resources/list 和 resources/read.

6.首次尝试提示

• “列出我保管库中的顶级文件和文件夹。”
• “创建 Inbox/HN Launch.md 有一份发射清单。"
• “将今天的状态更新添加到我的每日笔记中。”
• “显示已提及或链接到的笔记 HackerNews Launch."
• “创建一个名为的新客户端工作区 Acme 带有文件夹和索引注释。"

✨ 功能集

这个MCP服务器现在涵盖了人类在黑曜石中手动操作的更大范围：

• 通过Obsidian REST插件或直接文件系统访问在本地工作。
• 通过stdio和HTTP/SSE传输MCP。
• 将保管库笔记作为MCP资源公开 obsidian://vault/... URI。
• 跨三个注释范围工作：vault文件、活动注释和周期性注释。
• 以markdown、解析的笔记JSON或文档映射的形式阅读笔记，以进行结构推理。
• 创建、替换、追加、修补和删除笔记，而不是在只读自动化中停止。
• 涵盖语义搜索、标签列表、笔记移动、保险库统计、画布读取、看板解析、任务提取和图遍历。
• 在特定标题路径下附加 obsidian_smart_append.
• 具有细粒度目标操作的补丁标题、块或前端字段。
• 运行简单的文本搜索以及更丰富的Dataview DQL和JsonLogic vault查询。
• 检查外发链接、反向链接和纯文本提及机会。
• 在桌面UI中打开笔记，并从MCP执行黑曜石命令。
• 为新项目或客户提供带有索引注释的脚手架工作区文件夹结构。
• 当您需要较小的二进制文件并且可以跳过ONNX语义搜索时，请提供NativeAOT发布路径。

🛠 可用工具

💡 示例用途

• “查找我上个月关于路线图规划的会议记录。”
• “在中创建注释 Inbox/ 使用此对话中的行动项。"
• “将此摘要附加到 Projects/MCP.md."
• “设置前台 status 领域 Tasks/ship-docs.md 到 done."
• “列出我的文件 Daily/ 在创建今天的笔记之前。"
• “在今天的每日简报中附上一份独立摘要。”
• “将这些决定附在 Projects::Launch::Decisions，如果不存在，则创建航向路径。"
• “对标记的所有打开的任务运行数据视图查询 #hn-launch."
• “显示已链接到的笔记 Projects/HackerNews Launch.md 在创建副本之前。"
• 使用收件箱、项目、资源、存档和每日部分创建一个新的客户端工作区
• “阅读我的 Planning/Board.md 看板，按列汇总卡片。"
• “列出vault资源并阅读 obsidian://vault/Inbox.md 作为被动MCP上下文。"
• “执行Obsidian命令以打开命令面板或模板器工作流。”

✅ 质量检查

• dotnet build src/Mcp.Obsidian/Mcp.Obsidian.csproj
• dotnet test tests/Mcp.Obsidian.Tests/Mcp.Obsidian.Tests.csproj
• dotnet publish src/Mcp.Obsidian/Mcp.Obsidian.csproj -r linux-x64 -c Release
• GitHub Actions发布工作流为构建发布资产 linux-x64, linux-arm64, win-x64，以及 osx-arm64
• GitHub Actions CI在每次推送时自动运行 main

测试套件涵盖了markdown助手、图遍历、语义排名回退行为、文件系统模式、看板解析和反向链接分析。

📦 发布

此存储库包括GitHub Actions工作流 .github/works/ci.yml 和 .github/works/release.yml 即：

• ✅ 在上运行测试 main
• 📦 发布单文件自包含的二进制文件
• 🖥 Linux x64、Linux arm64、Windows x64和macOS Apple Silicon的软件包工件
• 🚀 当您推送以下标签时，将这些资产上传到GitHub Release v0.5.0

要剪切释放，请执行以下操作：

git tag v0.5.0
git push origin v0.5.0

🛡 安全和权限

• 本地执行： 此服务器完全在您的计算机上运行。除了您正在使用的LLM提供商之外，不会将任何数据发送到第三方云。
• HTTPS： 本地REST API使用自签名证书。这 VerifySsl: false 除非配置本地信任，否则需要设置。
• 访问范围： 在REST模式下，服务器只能访问本地REST API插件处于活动状态的vault。
• 文件系统模式： 在 --vault-path 在模式下，服务器直接访问vault文件夹，并阻止在配置的根目录之外的路径遍历。
• 配置： 保持 appsettings.json 本地到您的机器，并且永远不要提交您的Obsidian API密钥。

🔧 故障排除

• 如果MCP客户端无法连接，请确保Obsidian正在运行，并且本地REST API插件已启用。
• 如果您使用的是文件系统模式，请确保 --vault-path 指向vault根目录，并且进程可以读取该文件夹。
• 如果您使用的是HTTP模式，请确保选择 --http-port 是免费的，并向发送MCP POST请求 /mcp.
• 如果请求因身份验证错误而失败，请将API密钥从Obsidian重新复制到 appsettings.json.
• 如果TLS验证失败，请保留 VerifySsl 着手 false 除非您明确信任本地证书。
• 如果您的MCP客户端无法启动 dotnet run，首先发布应用程序，然后将客户端指向二进制文件 artifacts/obsidian-mcp.
• 如果标题的补丁失败，请将注释阅读为 document_map 首先检查API期望的准确航向路径。
• 如果Linux NativeAOT在macOS上发布失败，请在Linux运行器或本机Linux机器上构建RID，而不是在本地交联。

🗺 路线图

• [x] 基本CRUD（创建、读取、搜索、追加）。
• [x] 前线操纵。
• [x] 智能追加： 在特定的H2/H3标题下添加上下文。
• [x] 反向链接逻辑： 在创建新链接之前，对现有链接进行人工智能感知。
• [x] 每日笔记助手： 用于修改当前日记的快捷工具。
• [x] 指挥自动化： 从MCP列出并执行黑曜石命令。
• [x] 工作空间脚手架： 带有结构化文件夹和注释的Bootstrap项目或客户端工作区。
• [x] 图遍历（BFS/DFS）： 从起始音符遍历传入和传出音符关系。
• [ ] 模板和捕获流： 模板式工作流的一流助手。
• [ ] 图形感知规划： 在重写大音符之前进行更深入的链接图推理。

🤝 贡献

欢迎捐款。

1. 分叉回购。
2. 创建功能分支(git checkout -b feature/amazing-feature).
3. 提交你的更改。
4. 打开拉取请求。

📄 许可证

根据MIT许可证分发。看 LICENSE 了解更多信息。