Obsidian MCP 工具服务器

该项目提供了一个模型上下文协议（MCP）服务器，该服务器暴露了与Obsidian保险库交互的工具。

目录

• 功能
• 安装
• 配置
• 手动运行（用于测试/调试）
• 客户端配置（示例：Claude Desktop）
• 可用的MCP工具
• 路线图
• 常见问题解答（FAQ）
• 欢迎贡献！

功能

允许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中：

     source .venv/bin/activate 
     

   （终端提示符现在应显示 (.venv)）

5. 安装包及其依赖项：

   pip install . 
   

配置

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

1. 复制示例文件：

   # 从项目根目录（OMCP/）
   cp .env.example .env 
   

   （在Windows上，您可能需要使用 copy .env.example .env）

2. 编辑.env文件： 使用文本编辑器打开新创建的.env文件。

3. 设置OMCP_VAULT_PATH：这是唯一必需的变量。用您的Obsidian保险库的绝对路径更新它。即使在Windows上也使用正斜杠（/）作为路径分隔符。

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

4. 查看可选设置：根据需要调整其他OMCP_变量，例如每日笔记位置、服务器端口或备份目录。阅读文件中的注释以获取解释。

（或者，您可以不使用.env文件，而是将这些变量设置为实际的系统环境变量。如果两者都设置了，服务器会优先使用系统环境变量。）

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

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

1. 确保已完成配置：确保您已创建并配置了.env文件，如配置部分所述。
2. 激活虚拟环境：

   # 如果尚未激活
   .venv\Scripts\Activate.ps1 
   

   （在Linux/macOS上使用 source .venv/bin/activate）
3. 运行服务器脚本：

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

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

记住：如果您打算使用Claude Desktop或其他启动器使用此服务器，请不要像这样手动运行它。相反，请配置客户端应用程序（参见下一节），它将处理启动和停止服务器进程。

客户端配置（示例：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键下添加的一个示例条目：

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"],
      "env": {
        "OMCP_VAULT_PATH": "C:/path/to/your/Obsidian/Vault",
        "OMCP_DAILY_NOTE_LOCATION": "Journal/Daily"
      }
    }
  }
}

关键点：

• 替换与您的系统相关的绝对路径
• 对于command和args字段中的Windows路径：
  • 使用双反斜杠（\\）作为路径分隔符
  • 包括Python可执行文件的.exe扩展名
• 对于env块中的Windows路径：
  • 使用正斜杠（/）以获得更好的兼容性
  • 不包括.exe扩展名
• command路径必须指向您创建的.venv内的python.exe可执行文件
• args路径必须指向obsidian_mcp_server子文件夹内的main.py文件
• 使用env块是确保服务器能够找到您的保险库路径的最可靠方法
• 修改客户端应用的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_folderMCP工具。
  • 添加文件夹创建的测试。

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)。
• 插件集成工具：
  • Dataview集成：
    • 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）

配置问题

Q: 我的服务器找不到我的保险库。出了什么问题？ A: 这通常是由于路径配置不正确。检查：

1. .env文件中的OMCP_VAULT_PATH使用正斜杠（/），即使在Windows上也是如此
2. 路径是绝对路径（从根开始）
3. 路径末尾没有多余的斜杠
4. 保险库目录存在且可访问

Q: 为什么我会遇到权限错误？ A: 这通常发生在：

1. 保险库路径指向受限目录
2. Python进程没有读/写权限
3. 保险库位于当前同步的云同步文件夹（如OneDrive）中

尝试：

1. 将保险库移动到本地目录
2. 使用提升的权限运行服务器
3. 检查您的防病毒软件是否阻止访问

客户端连接问题

Q: 我的AI客户端无法连接到服务器。我应该检查什么？ A: 验证这些常见问题：

1. 服务器实际上正在运行（检查终端输出）
2. 客户端配置中的端口与服务器端口匹配
3. 客户端配置中的Python路径指向正确的虚拟环境
4. 客户端配置中的所有环境变量都已正确设置

Q: 为什么我会收到“连接被拒绝”错误？ A: 这通常意味着：

1. 服务器没有运行
2. 端口已被占用
3. 防火墙阻止了连接

尝试：

1. 检查服务器是否运行：netstat -ano | findstr :8001（Windows）
2. 尝试通过设置.env中的OMCP_SERVER_PORT使用不同的端口
3. 暂时禁用防火墙以进行测试

Q: 我收到了“[error] [obsidian_vault] 不期望的标记'S'，'Starting O'...不是有效的JSON”。出了什么问题？ A: 此错误发生在客户端的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路径格式的正确示例：

{
  "mcpServers": {
    "obsidian_vault": {
      "command": "C:\\path\\to\\your\\project\\OMCP\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\your\\project\\OMCP\\obsidian_mcp_server\\main.py"]
    }
  }
}

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

1. 服务器已经在另一个进程中运行
2. 端口已经被其他应用程序占用
3. 服务器进程意外终止

按顺序尝试以下步骤：

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

   # 在Windows上
   netstat -ano | findstr :8001
   # 查找PID，然后：
   taskkill /F /PID <PID>
   

   # 在Linux/macOS上
   lsof -i :8001
   # 查找PID，然后：
   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. 您系统事件日志中的任何错误消息

Q: 服务器立即断开连接，显示“服务器传输意外关闭...进程提前退出”。出了什么问题？ A: 这个错误意味着Python服务器进程几乎在被客户端启动后立即崩溃。这不是超时；服务器脚本本身未能运行或保持运行。

常见原因：

1. 客户端JSON中的路径不正确：
   • command没有指向.venv内的正确python.exe。
   • args没有指向正确的obsidian_mcp_server/main.py脚本。
   • Windows路径中的路径分隔符不正确或缺少反斜杠转义（\\）。
2. 缺少依赖项：
   • .venv中未安装requirements.txt中的必需包。
   • 客户端在没有正确激活虚拟环境的情况下启动Python。
3. 语法错误： 最近的代码更改引入了Python语法错误。
4. 关键配置/权限错误：
   • 启动时无法读取.env文件。
   • OMCP_VAULT_PATH无效或不可访问。
   • Python进程缺乏运行或访问文件的权限。
5. 早期未处理异常： 在服务器开始监听之前发生的初始设置期间出现错误。

故障排除步骤：

1. 验证客户端JSON路径： 仔细检查客户端JSON配置中的command和args的绝对路径。使用转义的反斜杠（\\）对Windows路径。
2. 手动测试（关键步骤）：
   • 在终端中激活虚拟环境：

     # 在Windows上
     .\.venv\Scripts\activate
     

     # 在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和保险库路径： 确保.env存在、可读且OMCP_VAULT_PATH正确（使用正斜杠/）。
5. 审查最近的代码更改： 检查最近编辑的Python文件中的语法错误或其他问题。

笔记操作

Q: 为什么我不能在某些文件夹中创建/编辑笔记？ A: 这可能是由于：

1. 路径安全限制（试图在保险库之外写入）
2. 文件夹权限
3. 其他进程锁定