Obsidian MCP 工具服务器

该项目提供了一个模型上下文协议（MCP）服务器，用于与 Obsidian 仓库进行交互的工具。

目录

• 功能
• 安装
• 配置
• 手动运行（用于测试/调试）
• 客户端配置（示例：Claude 桌面版）
• 可用的 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 桌面版这样的客户端应用程序会根据下面描述的配置自动启动服务器，但你也可以直接从终端手动运行服务器以进行直接测试或调试。

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

路线图

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

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

配置问题

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

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. 暂时禁用防火墙进行测试

问：我收到“[error] [obsidian_vault] Unexpected token 'S', "Starting O"... is not valid 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 路径格式示例：

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

问：我收到超时错误和“服务器断开连接”消息。发生了什么？
答：这种错误模式（初始化成功，然后在 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: 服务器立即断开连接，并显示“Server transport closed unexpectedly... process exiting early”。这是怎么回事？
A: 此错误表示 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. 手动测试（关键步骤）：
   • 在终端中激活虚拟环境：

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

笔记操作

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

1. 路径安全限制（尝试写入 Vault 外部）
2. 文件夹权限
3. 其他进程对文件的锁定

尝试：

1. 使用 Vault 内部的相对路径
2. 检查文件夹权限
3. 关闭可能打开这些文件的其他程序

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

1. 笔记路径不正确
2. 内容格式无效
3. 备份创建失败

检查：

1. 笔记路径存在且可访问
2. 内容是有效的 Markdown 格式
3. 备份目录具有写权限

日常笔记

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

1. .env 中的 OMCP_DAILY_NOTE_LOCATION 设置正确
2. 路径使用正斜杠
3. 目标文件夹存在
4. 日期格式与您的 Vault 设置匹配

一般故障排除

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

python test_client.py

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

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

1. 运行服务器的终端
2. 失败操作的备份目录
3. 权限问题的系统事件日志

问：如何重置一切以重新开始？
答：尝试以下步骤：

1. 停止服务器
2. 删除 .env 文件
3. 从 .env.example 创建一个新的 .env
4. 重启服务器

欢迎贡献！