另一个臃肿的黑曜石MCP服务器
\[！小心\] 🔴🔴🔴 实验项目-不用于生产🔴🔴🔴 这是一个实验项目，主要是通过使用Claude Code的人工智能辅助开发创建的，只需要最少的人为干预。它仅用于测试和学习目的。 本项目不得用于： - 生产环境 - 关键数据或重要保管库 - 数据完整性至关重要的任何场景 使用风险自负。代码可能包含错误、安全漏洞或意外行为。 支持通知： 该项目可能不会因第三方报告的错误或问题而受到关注。如果你有兴趣贡献或报告问题，你可能不会得到回应，因为这个项目可能不会长期维护。然而，在实验阶段之后，这种情况可能会改变。
______________________________________________________________________
一种模型上下文协议（MCP）服务器，为AI助手提供对黑曜石金库的安全访问。无需运行Obsidian即可读取、写入、搜索和管理笔记。
特性
- 直接文件系统访问 -无黑曜石跑步
- 多保险库支持 -同时管理多个保管库
- 可配置的工具组 -仅启用所需的功能
- 完整的CRUD操作 -创建、阅读、更新、删除笔记
- YAML前体 -解析和操作笔记元数据
- 标签管理 -按标签添加、删除和搜索
- 链接分析 -反向链接、外链接、孤立链接、断开链接、链接图
- 每日笔记 -创建和管理每日日记账分录
- 模板 -应用带有变量替换的模板
- 黑曜石基底 -基于过滤器查询动态笔记视图
- 批量操作 -高效处理多个笔记
- 附件跟踪 -列出并查找未使用的附件
- 备份系统 -创建和恢复笔记备份
- 安全第一 -路径遍历保护，防止符号链接逃逸
需求
- Node.js 18+
- npm或纱线
安装
# Clone the repository
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server
# Install dependencies
npm install
# or
yarn install
# Build (optional - can run directly with tsx)
npm run build快速开始
# Start the server with a vault
npm start /path/to/your/vault
# With specific tool groups
npm start /path/to/your/vault --tools=vault,notes,search
# With a custom vault name
npm start /path/to/your/vault my-vault配置
选项1:克劳德代码CLI（推荐）
# Add the MCP server
claude mcp add obsidian \
--transport stdio \
--scope user \
-- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault
# With specific tool groups
claude mcp add obsidian \
--transport stdio \
--scope user \
-- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault --tools=vault,notes,search范围选项：
user-在所有项目中都可用（保存在~/.claude.json)local-仅限当前项目project-与团队共享（保存在.mcp.json)
有用的命令：
claude mcp list # List configured servers
claude mcp get obsidian # View server details
claude mcp remove obsidian # Remove server选项2：手动配置
编辑 ~/.claude.json:
{
"mcpServers": {
"obsidian": {
"type": "stdio",
"command": "npx",
"args": [
"tsx",
"/path/to/obsidian-mcp-server/src/index.ts",
"/path/to/your/vault",
"--tools=vault,notes,search"
]
}
}
}选项3:Claude桌面应用程序
在以下位置编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"tsx",
"/path/to/obsidian-mcp-server/src/index.ts",
"/path/to/your/vault",
"--tools=vault,notes,search"
]
}
}
}工具组
| 组 | 工具 | 描述 |
|---|---|---|
vault | list_vaults、set_active_vault、register_vault | vault管理 |
notes | list_notes、read_note、create_note、update_note、delete_note、rename_note、move_note | 注意CRUD操作 |
search | search_vault | 全文搜索 |
frontmatter | get_frontmatter、update_frontmatter、remove_frontmatter_field、add_to_ray_field、remove.from_array_field | YAML元数据 |
tags | list_tag、add_tag、remove_tag、search_by_tag | 标签管理 |
links | get_outlinks、get_backlinks、find_orphans、find_breack_links、get_link_graph | 链接分析 |
daily | get_daily_note、create_daily_note、list_daily_notes、append_to_daily | 每日笔记 |
templates | list_templates、get_template、apply_template、create_from_template | 模板系统 |
bases | list_base、get_base、query_base | 黑曜石基 |
batch | batch_move、batch_delete、batch_update_frontmatter、batch_add_tag、batch_remove_tag、batch-read_notes | 批处理操作 |
attachments | list_attachments、get_attachment_info、find_unused_attachments、get_attachments_in_note | 附件管理 |
backup | create_note_backup、list_backups、restore_backup和delete_old_backups | 备份系统 |
特殊值：
all-启用所有工具组（默认）none-禁用所有工具（用于测试）
配置示例
只读访问
--tools=vault,notes,search无需修改注释即可安全探索。
日常生产力
--tools=vault,notes,search,daily,tags快速捕获、每日笔记和标签组织。
知识分析
--tools=vault,notes,search,links,tags探索联系，找到孤儿，分析知识图谱。
内容创作
--tools=vault,notes,search,templates,frontmatter从模板创建笔记，管理元数据。
完全访问权限
--tools=all所有功能均已启用。
多保险库设置
创建 ~/.obsidian-mcp/config.json:
{
"vaults": {
"personal": "/Users/you/Obsidian/Personal",
"work": "/Users/you/Obsidian/Work",
"research": "/Users/you/Obsidian/Research"
},
"defaultVault": "personal"
}使用以下命令在保管库之间切换 set_active_vault 工具。
环境变量
| 变量 | 描述 |
|---|---|
OBSIDIAN_MCP_TOOLS | 以逗号分隔的工具组列表 |
LOG_LEVEL | 日志记录级别：调试、信息、警告、错误 |
CLI 参考
# Show help
npm start -- --help
# Start with vault
npm start /path/to/vault [vault-name] [--tools=groups]
# Examples
npm start /path/to/vault # All tools
npm start /path/to/vault my-vault # With custom name
npm start /path/to/vault --tools=vault,notes # Specific groups故障排除
服务器未连接
- 验证vault路径是否存在并且是绝对路径
- 检查Node.js版本：
node --version（要求18+） - 手动测试：
npm start /path/to/vault - 对于克劳德代码：使用
/mcp检查状态和错误 - 对于Claude Desktop：检查登录
~/Library/Logs/Claude/mcp*.log
“工具X未启用”错误
您尝试使用的工具不在您启用的组中。检查你的 --tools 配置并添加所需的组。
权限错误
确保运行MCP服务器的用户具有对vault目录的读/写访问权限。
未找到路径
- 使用绝对路径，而不是相对路径
- 确保保险库包含
.obsidian文件夹 - 检查路径中的拼写错误
发展
# Development mode (auto-reload)
npm run dev
# Build
npm run build
# Type check
npx tsc --noEmit
# Run tests
npm test
# Run tests with coverage
npm run test:coverage文档
安全
此服务器实施了多种安全措施：
- 路径验证 -防止路径遍历攻击
- Symlink保护 -阻止符号链接转义尝试
- 输入验证 -所有输入均已Zod模式验证
- 保留名称阻止 -防止系统文件冲突
看 安全.md 了解详情。
灵感
这个项目的灵感来自 mcp黑曜岩.
许可证
麻省理工学院