使用说明

黑曜岩mcp

一个快速的MCP（模型上下文协议）服务器，为人工智能助手提供支持 完全读/写访问 到你的黑曜石金库。

✨ 特性

特性	描述
📖 阅读笔记	从vault中的任何笔记中获取内容
✏️ 创建笔记	使用markdown内容创建新笔记
📝 更新备注	修改现有笔记
🗑️ 删除笔记	安全地将笔记移到垃圾桶
🔍 按标题搜索	按文件名查找笔记
📄 全文搜索	在笔记内容中搜索
📁 浏览文件夹	浏览您的保险库结构
🏷️ 获取标签	列出整个保管库中使用的所有标签
📅 汽车前部	自动添加创建/修改日期

🆕 自动前置器（v0.2.0）

在创建新笔记时，MCP会自动添加YAML frontmatter：

---
created: 2026-01-29
modified: 2026-01-29
tags: []
---

create_note：自动生成 created 和 modified 日期
update_note：自动更新 modified 编辑日期
可以禁用 auto_frontmatter: false

🚀 为什么？

	黑曜石mcp	云API
阅读笔记	✅	✅
写笔记	✅	❌
速度	⚡ 即时	🐌 网络延迟
离线	✅	❌
费率限制	无	是
API密钥	不需要	必需
隐私	100%本地	云同步

⚡ 性能（估计）

操作	20000张钞票
列出注释	0.17秒
完整内容已阅读	0.63秒
全文搜索	0.66秒

📋 需求

Python 3.10+
黑曜石安装
紫外线包管理器（推荐）

📦 安装

步骤1:克隆此存储库

git clone https://github.com/drtknoh-sudo/obsidian-mcp.git
cd obsidian-mcp

步骤2：安装依赖项

uv sync

步骤3：配置Claude桌面

打开您的Claude Desktop配置文件：

macOS：

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

窗户：

%APPDATA%\Claude\claude_desktop_config.json

添加黑曜石服务器配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/obsidian-mcp", "obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

重要提示： 用实际路径替换路径：

/path/to/uv → 查找 which uv （例如。， /Users/yourname/.local/bin/uv)
/path/to/obsidian-mcp → 你在哪里克隆了这个仓库
/path/to/your/vault → 您的黑曜石保险库文件夹

步骤4:重新启动克劳德桌面

完全退出并重新打开Claude Desktop。

🛠️ 可用工具

工具	说明
`list_notes`	列出注释（可选：按文件夹筛选）
`get_note`	阅读特定笔记的内容
`create_note`	创建新笔记（自动添加带日期的前件）
`update_note`	更新现有注释（自动更新修改日期）
`delete_note`	将便条移至.trase
`search_notes`	按标题搜索
`full_text_search`	搜索笔记内容
`list_folders`	列出所有文件夹
`get_tags`	获取所有标签
`get_vault_info`	获取保险库统计信息

💬 示例用法

配置后，您可以询问Claude：

“列出我最近的笔记”
“查找有关“项目规划”的注释”
“创建一个名为“会议笔记”的新笔记，其中包含今天的日期”
“搜索包含“API文档”的注释”
“我在保险库中使用哪些标签？”
“用新项目更新我的TODO笔记”

🔒 安全

100%本地：所有数据都保留在您的机器上
没有API密钥：不需要外部服务
保险箱沙盒：无法访问vault之外的文件
安全删除：删除移动到.trash，不是永久性的

🐛 故障排除

“未找到保险库”

确保 OBSIDIAN_VAULT_PATH 指向有效的黑曜石保管库文件夹。

Claude Desktop中的“服务器已断开连接”

检查一下 uv 路径正确（使用完整路径）
验证黑曜石mcp目录路径是否正确
检查Claude Desktop日志是否有错误

权限被拒绝（macOS）

授予对终端的全磁盘访问权限：系统偏好设置→ 安全与隐私→ 隐私→ 完全磁盘访问

📄 许可证

MIT许可证-请参阅许可证

🤝 贡献

欢迎投稿！请阅读贡献.md 第一。

🙏 致谢

建于 MCP（模型上下文协议）
受到黑曜石社区的启发