Obsidian MCP 工具服务器

该项目提供了一个模型上下文协议 (MCP) 服务器，它公开了与 Obsidian 保险库交互的工具。

目录

• 特征

• 安装

• 配置

• 手动运行（用于测试/调试）

• 客户端配置（例如：Claude Desktop）

• 可用的 MCP 工具

• 路线图

• 常见问题 (FAQ)

• 欢迎贡献！

Related MCP server: Obsidian MCP REST Server

特征

允许 MCP 客户端（如 AI 助手）执行以下操作：

• 阅读和写笔记

• 管理笔记元数据（前言）

• 列出笔记和文件夹

• 按内容或元数据搜索笔记

• 管理日常笔记

• 获取出站链接、反向链接和标签

安装

1. 克隆存储库（如果还没有）：

   # git clone <repository-url> # cd OMCP

2. 导航到项目目录：

   cd /path/to/your/OMCP

3. 创建 Python 虚拟环境（建议避免依赖冲突）：

   python -m venv .venv

4. 激活虚拟环境：

   • 在 Windows PowerShell 上：

     .venv\Scripts\Activate.ps1

   • 在 Linux/macOS 上：

     GXP5（您的终端提示符现在应该在开头显示(.venv) ）

5. 安装软件包及其依赖项：

   pip install .

配置

该服务器使用环境变量进行配置，可以使用项目根目录中的.env文件方便地进行管理。

1. 复制示例文件：

   # From the project root directory (OMCP/) cp .env.example .env

   （在 Windows 上，您可以使用copy .env.example .env ）

2. **编辑.env文件：**在文本编辑器中打开新创建的.env文件。

3. 设置变量。请使用 Obsidian 保管库的绝对路径进行更新。即使在 Windows 上，也请使用正斜杠 ( / ) 表示路径。

   OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"

4. **查看可选设置：**根据需要调整其他OMCP_变量，用于设置每日笔记、服务器端口或备份目录。请参阅文件中的注释以获取相关说明。

（或者，您也可以不使用

手动运行（用于测试/调试）

虽然像 Claude Desktop 这样的客户端应用程序将使用下面描述的配置自动启动服务器，但您也可以从终端手动运行服务器进行直接测试或调试。

1. **确保配置完成：**确保您已按照配置部分中的说明创建并配置了.env文件。

2. 激活虚拟环境：

   # If not already active .venv\Scripts\Activate.ps1

   （在 Linux/macOS 上使用

3. 运行服务器脚本：

   (.venv) ...> python obsidian_mcp_server/main.py

服务器将启动并打印其正在监听的地址（例如http://127.0.0.1:8001 ）。测试完成后，通常按Ctrl+C停止服务器。

请记住：像这样手动运行它。请改为配置客户端应用程序（请参阅下一节），它将负责启动和停止服务器进程。

客户端配置（例如：Claude Desktop）

许多 MCP 客户端（例如 Claude Desktop）可以直接启动服务器进程。要配置这样的客户端，通常需要编辑其 JSON 配置文件（例如，在 macOS/Linux 上是claude_desktop_config.json ，在 Windows 上则在AppData下找到对应的路径）。

⚠️重要的 JSON 格式规则：

1. JSON 文件不支持注释（删除任何//或/* */注释）

2. 所有字符串必须用双引号（ " ）正确引用

3. Windows 路径必须使用转义反斜杠 ( \\ )

4. 使用 JSON 验证器（如jsonlint.com ）检查语法

以下是在客户端 JSON 配置中的mcpServers键下添加的示例条目：

要点：

• 将路径替换为与您的系统相关的绝对路径

• 对于command和args字段中的 Windows 路径：

  • 使用双反斜杠 ( \\ ) 作为路径分隔符

  • 包含 Python 可执行文件的.exe扩展名

• 对于env块中的 Windows 路径：

  • 使用正斜杠（ / ）以获得更好的兼容性

  • 不要包含.exe扩展名

• command路径必须指向您创建的.venv内的python.exe可执行文件

• args路径必须指向obsidian_mcp_server子文件夹中的main.py文件

• 使用env块是确保服务器找到你的 Vault 路径的最可靠方法

• 修改 JSON 配置后，请记住重新启动客户端应用程序

应避免的常见陷阱：

1. 不要在 Windows 路径中使用单反斜杠

2. 不要在 JSON 中包含注释

3. 不要忘记在 Windows 路径中转义反斜杠

4. 不要在同一路径中混合使用正斜杠和反斜杠

5. 不要忘记正确引用所有字符串

可用的 MCP 工具

• list_folders

• list_notes

• get_note_content

• get_note_metadata

• get_outgoing_links

• get_backlinks

• get_all_tags

• search_notes_content

• search_notes_metadata

• search_folders

• create_note

• edit_note

• append_to_note

• update_note_metadata

• delete_note

• get_daily_note_path

• create_daily_note

• append_to_daily_note

路线图

有关包括错误处理注意事项在内的详细分阶段实施计划，请参阅ROADMAP.md文件。

该项目正在积极开发中。以下是计划中的功能：

v1.x（近期）

• 基于模板的笔记创建：

  • 配置模板目录（ OMCP_TEMPLATE_DIR ）。

  • 实现create_note_from_template工具（使用模板名称、目标路径、可选元数据）。

  • 添加模板创建的测试。

• 文件夹创建：

  • 实现create_folder实用程序函数。

  • 实现create_folder MCP 工具。

  • 添加文件夹创建测试。

v1.y（中期/未来增强）

• 模板中的变量替换（例如， {{DATE}} ）。

• list_templates工具。

• 高级注释更新工具（例如， append_to_note_by_metadata ）。

• list_vault_structure工具用于全面的保险库层次结构视图。

• 全面的测试审查和扩展。

v2.x+（潜在想法/长期）

• 组织工具：

  • move_item(source, destination) （初始版本可能不会更新链接）。

  • rename_item(path, new_name) （初始版本可能不会更新链接）。

• 内容操作工具：

  • replace_text_in_note(path, old, new, count) 。

  • prepend_to_note(path, content) 。

  • append_to_section(path, heading, content) （需要可靠的标题解析）。

• 查询工具：

  • get_local_graph(path) （合并传出/反向链接）。

  • search_notes_by_metadata_field(key, value) 。

• 插件集成工具：

  • 数据视图集成：

    • execute_dataview_query(query_type, query) - 运行 Dataview 查询并获取结构化结果

    • search_by_dataview_field(field, value) - 通过 Dataview 字段搜索笔记

  • 任务管理：

    • query_tasks(status, due_date, tags) - 在保险库中搜索和过滤任务

  • 看板集成：

    • get_kanban_data(board_path) - 获取结构化看板数据

  • 日历集成：

    • get_calendar_events(start_date, end_date) - 查询日历事件和任务

常见问题 (FAQ)

配置问题

**问：我的服务器找不到我的保管库。怎么回事？**答：这通常是由于路径配置不正确造成的。请检查：

1. .env文件中的OMCP_VAULT_PATH即使在 Windows 上也使用正斜杠 ( / )

2. 该路径是绝对路径（从根目录开始）

3. 路径没有以斜杠结尾

4. 保管库目录存在且可访问

**问：为什么我会收到权限错误？**答：这通常发生在以下情况：

1. 保管库路径指向受限目录

2. Python 进程没有读/写权限

3. 保管库位于当前正在同步的云同步文件夹（如 OneDrive）中

尝试：

1. 将您的保管库移动到本地目录

2. 使用提升的权限运行服务器

3. 检查你的防病毒软件是否阻止访问

客户端连接问题

**问：我的 AI 客户端无法连接到服务器。我应该检查什么？**答：请验证以下常见问题：

1. 服务器实际上正在运行（检查终端输出）

2. 客户端配置中的端口与服务器的端口匹配

3. 客户端配置中的 Python 路径指向正确的虚拟环境

4. 所有环境变量均在客户端配置中正确设置

**问：为什么我会收到“连接被拒绝”的错误？**答：这通常意味着：

1. 服务器未运行

2. 该端口已被使用

3. 防火墙阻止了连接

尝试：

1. 检查服务器是否正在运行： netstat -ano | findstr :8001 （Windows）

2. 通过在.env中设置OMCP_SERVER_PORT来尝试不同的端口

3. 暂时禁用防火墙进行测试

**问：我收到“[错误] [obsidian_vault] 意外的令牌‘S’，‘起始 O’... 不是有效的 JSON”。这是什么问题？**答：当客户端的 JSON 配置文件格式错误时，就会发生此错误。常见原因：

1. JSON 中缺少或多余的逗号

2. Windows 路径中未转义的反斜杠

3. JSON 中的注释（JSON 不支持注释）

检查您的客户端配置文件（例如， claude_desktop_config.json ）：

1. 使用 JSON 验证器（如jsonlint.com ）检查语法

2. 对于 Windows 路径，转义反斜杠： "C:\\path\\to\\file"

3. 删除所有注释（// 或 /* */）

4. 确保所有字符串都正确引用

5. 检查所有括号和大括号是否正确闭合

正确的 Windows 路径格式示例：

**问：我收到超时错误和“服务器已断开连接”消息。发生了什么？**答：这种错误模式（初始化成功，然后在 60 秒后超时）通常意味着：

1. 服务器已在另一个进程中运行

2. 该端口已被另一个应用程序使用

3. 服务器进程意外终止

请按顺序尝试以下步骤：

1. 检查正在运行的服务器进程：

   # On Windows netstat -ano | findstr :8001 # Look for the PID and then: taskkill /F /PID <PID>
   # On Linux/macOS lsof -i :8001 # Look for the PID and then: kill -9 <PID>

2. 检查使用该端口的其他应用程序：

   • 关闭可能使用端口 8001 的任何其他应用程序

   • 这包括其他 MCP 服务器、开发服务器或任何 Web 应用程序

   • 如果您不确定，请尝试更改.env中的端口：

     OMCP_SERVER_PORT=8002

3. 验证服务器进程：

   • 打开任务管理器 (Windows) 或活动监视器 (macOS)

   • 查找与 MCP 服务器相关的任何 Python 进程

   • 结束任何可疑进程

4. 检查系统资源：

   • 确保有足够的内存和 CPU 可用

   • 检查是否有任何防病毒软件或安全软件阻止该过程

   • 验证您的 Python 环境具有适当的权限

5. 重置所有内容：

   • 停止客户端应用程序

   • 终止所有剩余的服务器进程

   • 删除.env文件并从.env.example创建一个新文件

   • 重新启动计算机（如果其他步骤不起作用）

   • 从客户端应用程序重新开始

如果尝试所有这些步骤后问题仍然存在，请分享：

1. 完整的错误日志

2. netstat -ano | findstr :8001 (Windows) 或lsof -i :8001 (Linux/macOS) 的输出

3. 系统事件日志中的任何错误消息

**问：服务器立即断开连接，并显示“服务器传输意外关闭……进程提前退出”。这是什么问题？**答：此错误意味着 Python 服务器进程在被客户端启动后几乎立即崩溃。这不是超时；服务器脚本本身无法运行或无法保持运行。

常见原因：

1. 客户端 JSON 中的路径不正确：

   • command没有指向.venv内的正确的python.exe 。

   • args没有指向正确的obsidian_mcp_server/main.py脚本。

   • Windows 上的路径分隔符不正确或缺少反斜杠转义符 ( \\ )。

2. 缺少依赖项：

   • requirements.txt中所需的包未安装在.venv中。

   • 客户端在没有正确激活虚拟环境的情况下启动了 Python。

3. **语法错误：**最近的代码更改引入了 Python 语法错误。

4. 严重配置/权限错误：

   • 启动时读取.env文件时出错。

   • OMCP_VAULT_PATH无效或无法访问。

   • Python 进程缺少运行或访问文件的权限。

5. **早期未处理的异常：**在服务器开始监听之前的初始设置期间发生错误。

故障排除步骤：

1. **验证客户端 JSON 路径：**仔细检查客户端 JSON 配置中command和args的绝对路径。对于 Windows 路径，请使用转义反斜杠 ( \\ )。

2. 手动测试（关键步骤）：

   • 在终端中激活虚拟环境：

     # On Windows .\.venv\Scripts\activate
     # On Linux/macOS source .venv/bin/activate

   • 直接运行服务器：

     python obsidian_mcp_server/main.py

   • 仔细查看终端中直接打印的任何错误消息。这可以绕过客户端，通常可以揭示根本原因（例如ImportError 、 SyntaxError 、 FileNotFoundError ）。

3. **检查依赖项：**激活 venv 后，运行pip check和pip install -r requirements.txt 。

4. **验证.env和 Vault Path：**确保.env存在、可读且OMCP_VAULT_PATH正确（使用正斜杠/ ）。

5. **查看最近的代码更改：**检查最近编辑的 Python 文件中的语法错误或问题。

注意操作

**问：为什么我无法在某些文件夹中创建/编辑笔记？**答：这可能是因为：

1. 路径安全限制（尝试写入保险库外部）

2. 文件夹权限

3. 来自其他进程的文件锁

尝试：

1. 在保管库中使用相对路径

2. 检查文件夹权限

3. 关闭可能打开该文件的其他程序

**问：为什么我的笔记更新没有保存？**答：常见原因：

1. 注释路径不正确

2. 内容格式无效

3. 备份创建失败

查看：

1. 注释路径存在且可访问

2. 内容是有效的 markdown

3. 备份目录有写入权限

每日笔记

**问：为什么我的每日笔记没有创建在正确的位置？**答：请验证：

1. OMCP_DAILY_NOTE_LOCATION在.env中设置正确

2. 路径使用正斜杠

3. 目标文件夹存在

4. 日期格式与您的保险库设置相匹配

常规故障排除

**问：如何检查服务器是否正常工作？**答：运行测试客户端：

这将执行一系列操作并报告任何问题。

**问：我在哪里可以找到错误日志？**答：检查：

1. 服务器运行的终端

2. 失败操作的备份目录

3. 权限问题的系统事件日志

**问：如何重置所有内容以重新开始？**答：请尝试以下步骤：

1. 停止服务器

2. 删除.env文件

3. 从.env.example创建一个新的.env

4. 重启服务器

欢迎贡献！