Obsidian MCP 工具服务器

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

特征

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

阅读和写笔记
管理笔记元数据（前言）
列出笔记和文件夹
按内容或元数据搜索笔记
管理日常笔记
获取出站链接、反向链接和标签

安装

克隆存储库（如果还没有）：
# git clone <repository-url> # cd OMCP
导航到项目目录：
cd /path/to/your/OMCP
创建 Python 虚拟环境（建议避免依赖冲突）：
python -m venv .venv
激活虚拟环境：
- 在 Windows PowerShell 上：
  .venv\Scripts\Activate.ps1
- 在 Linux/macOS 上：GXP5（您的终端提示符现在应该在开头显示(.venv) ）
安装软件包及其依赖项：
pip install .

配置

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

复制示例文件：
# From the project root directory (OMCP/) cp .env.example .env
（在 Windows 上，您可以使用copy .env.example .env ）
**编辑.env文件：**在文本编辑器中打开新创建的.env文件。
设置OMCP_VAULT_PATH ：这是唯一必需的变量。请使用 Obsidian 保管库的绝对路径进行更新。即使在 Windows 上，也请使用正斜杠 ( / ) 表示路径。
OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault"
**查看可选设置：**根据需要调整其他OMCP_变量，用于设置每日笔记、服务器端口或备份目录。请参阅文件中的注释以获取相关说明。

（或者，您也可以不使用.env文件，而是将它们设置为实际的系统环境变量。如果同时设置了系统环境变量和.env文件，则服务器将优先考虑系统环境变量。）

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

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

**确保配置完成：**确保您已按照配置部分中的说明创建并配置了.env文件。
激活虚拟环境：
# If not already active .venv\Scripts\Activate.ps1
（在 Linux/macOS 上使用source .venv/bin/activate ）
运行服务器脚本：
(.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 格式规则：

JSON 文件不支持注释（删除任何//或/* */注释）
所有字符串必须用双引号（ " ）正确引用
Windows 路径必须使用转义反斜杠 ( \\ )
使用 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块是确保服务器找到你的 Vault 路径的最可靠方法
修改 JSON 配置后，请记住重新启动客户端应用程序

应避免的常见陷阱：

不要在 Windows 路径中使用单反斜杠
不要在 JSON 中包含注释
不要忘记在 Windows 路径中转义反斜杠
不要在同一路径中混合使用正斜杠和反斜杠
不要忘记正确引用所有字符串

可用的 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) 。
插件集成工具：
- 数据视图集成：
  - 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)

配置问题

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

.env文件中的OMCP_VAULT_PATH即使在 Windows 上也使用正斜杠 ( / )
该路径是绝对路径（从根目录开始）
路径没有以斜杠结尾
保管库目录存在且可访问

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

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

尝试：

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

客户端连接问题

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

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

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

服务器未运行
该端口已被使用
防火墙阻止了连接

尝试：

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

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

JSON 中缺少或多余的逗号
Windows 路径中未转义的反斜杠
JSON 中的注释（JSON 不支持注释）

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

使用 JSON 验证器（如jsonlint.com ）检查语法
对于 Windows 路径，转义反斜杠： "C:\\path\\to\\file"
删除所有注释（// 或 /* */）
确保所有字符串都正确引用
检查所有括号和大括号是否正确闭合

正确的 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 秒后超时）通常意味着：

服务器已在另一个进程中运行
该端口已被另一个应用程序使用
服务器进程意外终止

请按顺序尝试以下步骤：

检查正在运行的服务器进程：
# 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>
检查使用该端口的其他应用程序：
- 关闭可能使用端口 8001 的任何其他应用程序
- 这包括其他 MCP 服务器、开发服务器或任何 Web 应用程序
- 如果您不确定，请尝试更改.env中的端口：
  OMCP_SERVER_PORT=8002
验证服务器进程：
- 打开任务管理器 (Windows) 或活动监视器 (macOS)
- 查找与 MCP 服务器相关的任何 Python 进程
- 结束任何可疑进程
检查系统资源：
- 确保有足够的内存和 CPU 可用
- 检查是否有任何防病毒软件或安全软件阻止该过程
- 验证您的 Python 环境具有适当的权限
重置所有内容：
- 停止客户端应用程序
- 终止所有剩余的服务器进程
- 删除.env文件并从.env.example创建一个新文件
- 重新启动计算机（如果其他步骤不起作用）
- 从客户端应用程序重新开始

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

完整的错误日志
netstat -ano | findstr :8001 (Windows) 或lsof -i :8001 (Linux/macOS) 的输出
系统事件日志中的任何错误消息

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

常见原因：

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

故障排除步骤：

**验证客户端 JSON 路径：**仔细检查客户端 JSON 配置中command和args的绝对路径。对于 Windows 路径，请使用转义反斜杠 ( \\ )。
手动测试（关键步骤）：
- 在终端中激活虚拟环境：
  # On Windows .\.venv\Scripts\activate
  # On Linux/macOS source .venv/bin/activate
- 直接运行服务器：
  python obsidian_mcp_server/main.py
- 仔细查看终端中直接打印的任何错误消息。这可以绕过客户端，通常可以揭示根本原因（例如ImportError 、 SyntaxError 、 FileNotFoundError ）。
**检查依赖项：**激活 venv 后，运行pip check和pip install -r requirements.txt 。
**验证.env和 Vault Path：**确保.env存在、可读且OMCP_VAULT_PATH正确（使用正斜杠/ ）。
**查看最近的代码更改：**检查最近编辑的 Python 文件中的语法错误或问题。

注意操作

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

路径安全限制（尝试写入保险库外部）
文件夹权限
来自其他进程的文件锁

尝试：

在保管库中使用相对路径
检查文件夹权限
关闭可能打开该文件的其他程序

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

注释路径不正确
内容格式无效
备份创建失败

查看：

注释路径存在且可访问
内容是有效的 markdown
备份目录有写入权限

每日笔记

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

OMCP_DAILY_NOTE_LOCATION在.env中设置正确
路径使用正斜杠
目标文件夹存在
日期格式与您的保险库设置相匹配

常规故障排除

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

python test_client.py

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

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

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

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

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

欢迎贡献！

Obsidian MCP Tool Server

Integrations