使用说明

黑曜石MCP工具服务器

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

特性

允许MCP客户端（如AI助手）：

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

安装

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

配置

此服务器使用环境变量进行配置，可以使用 .env 项目根目录中的文件。

复制示例文件：
```
# From the project root directory (OMCP/)
cp .env.example .env 
```
（在Windows上，您可能会使用 copy .env.example .env)
编辑 .env 文件： 打开新创建的 .env 文本编辑器中的文件。
集 OMCP_VAULT_PATH: 这是唯一的 必需的 变量。用更新 绝对路径 到你的黑曜石金库。使用正斜杠(/)对于路径，即使在Windows上也是如此。
```
OMCP_VAULT_PATH="/path/to/your/Obsidian/Vault" 
```
查看可选设置： 调整另一个 OMCP_ 用于每日笔记、服务器端口或备份目录的变量（如果需要）。阅读文件中的注释以获取解释。

（或者，不使用 .env 文件中，您可以将这些设置为实际的系统环境变量。服务器将优先考虑系统环境变量 .env 如果两者都已设置，则返回文件。)

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

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

确保配置完成： 确保您已创建并配置了 .env 文件，如配置部分所述。
激活虚拟环境：
```
# If not already active
.venv\Scripts\Activate.ps1 
```
（使用 source .venv/bin/activate 在Linux/macOS上）

运行服务器脚本：

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

服务器将启动并打印它正在监听的地址（例如。， http://127.0.0.1:8001).你通常会按下 Ctrl+C 测试结束后停止它。

记得： 如果您打算将此服务器与Claude Desktop或类似的启动器一起使用，您应该不像这样手动运行它。改为配置客户端应用程序（见下一节），它将处理启动和停止服务器进程。

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

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

⚠️ 重要的JSON格式规则：

JSON文件不要支持评论（删除任何 // 或 /* */ 评论）
所有字符串都必须用双引号正确引号括起来(")
Windows路径必须使用转义反斜杠(\\)
使用JSON验证器（如 Jsonlin.com)检查语法

下面是一个要添加的示例条目 mcpServers 键入客户端的JSON配置：

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

要点：

将路径替换为 绝对路径 与您的系统相关
对于Windows中的路径 command 和 args 领域：
- 使用双反睫毛(\\)用于路径分隔符
- 包括 .exe Python可执行文件的扩展
对于Windows中的路径 env 块：
- 使用正斜杠(/)为了更好的兼容性
- 不包括 .exe 扩展
这 command 路径必须指向 python.exe 可执行内部这 .venv 你创造了
这 args 路径必须指向 main.py 文件内 obsidian_mcp_server 子文件夹
使用 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

路线图

有关包括错误处理注意事项的详细分阶段实施计划，请参阅 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 用于全面查看vault层次结构的工具。
全面的测试审查和扩展。

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) -跨vault搜索和筛选任务
- 看板集成：
  - get_kanban_data(board_path) -获取结构化看板数据
- 日历集成：
  - get_calendar_events(start_date, end_date) -查询日历事件和任务

常见问题（FAQ）

配置问题

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

这 OMCP_VAULT_PATH 在你的 .env 文件使用正斜杠(/)即使在Windows上
路径是绝对的（从根开始）
路径不会以尾随斜线结束
vault目录存在并且可以访问

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

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

尝试：

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

客户端连接问题

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

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

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

服务器未运行
端口已在使用中
防火墙正在阻止连接

尝试：

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

Q：我得到“[error][obsidian_vault]意外的令牌'S'，“起始O”…不是有效的JSON”。发生了什么？ A：当客户端的JSON配置文件格式错误时，会发生此错误。常见原因：

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

检查您的客户端配置文件（例如。， claude_desktop_config.json):

使用JSON验证器（如 Jsonlin.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"]
    }
  }
}

Q：我收到超时错误和“服务器已断开连接”消息。发生什么事了？ A：这种错误模式（初始化成功，然后在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）
系统事件日志中的任何错误消息

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

常见原因：

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

故障排除步骤：

验证客户端JSON路径： 仔细检查绝对路径 command 和 args 在客户端的JSON配置中。使用转义的反斜杠(\\)对于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 和保险库路径： 确保 .env 存在，可读，以及 OMCP_VAULT_PATH 正确（使用正斜杠 /).
查看最近的代码更改： 检查最近编辑的Python文件中是否存在语法错误或问题。

注释操作

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

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

尝试：

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

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

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

检查：

注释路径存在且可访问
内容为有效降价
备份目录具有写入权限

每日笔记

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

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

一般故障排除

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

python test_client.py

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

Q：我在哪里可以找到错误日志？ A：检查：

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

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

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

欢迎投稿！

使用说明

黑曜石MCP工具服务器

目录

特性

安装

配置

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

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

可用的MCP工具

路线图

常见问题（FAQ）

配置问题

客户端连接问题

注释操作

每日笔记

一般故障排除

相关 MCP

Qdrant向量搜索MCP服务器

进程执行工具

Unity编辑器MCP服务器

Claude Code开发工具包

AppleScript执行服务

Obsidian笔记搜索服务