使用说明
黑曜石MCP服务器
一个模型上下文协议（MCP）服务器，用于通过人工智能对话管理黑曜石金库笔记。该服务器使AI助手能够无缝地在黑曜石金库中创建、搜索和分析笔记。
特性
- ✅ 从对话中创建笔记 -从AI对话中自动生成结构化笔记
- ✅ 按内容和标签搜索笔记 -使用全文搜索和标签筛选查找现有笔记
- ✅ 获取笔记结构和元数据 -检索特定笔记的详细信息
- ✅ 自动前体格式化 -注释包括带有元数据的适当的YAML frontmatter
- ✅ 文件夹组织 -在vault中的自定义文件夹中组织笔记
- ✅ 时间戳跟踪 -自动创建和修改时间戳
- ✅ 标签管理 -使用可自定义标签自动标记
先决条件
- Node.js 18+
- 黑曜石拱顶
- MCP兼容的AI客户端（克劳德桌面等）
安装
# Clone the repository
git clone <repository-url>
cd obsidian-mcp
# Install dependencies
npm install
# Build the TypeScript code
npm run build
配置
方法1：环境变量（推荐）
设置黑曜石保险库的路径：
export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
将此添加到您的shell配置文件中(~/.bashrc, ~/.zshrc等）使其永久化。
方法2：配置文件
编辑 config/default.json:
{
"vaultPath": "/path/to/your/vault",
"defaultFolder": "MCP Notes",
"dateFormat": "YYYY-MM-DD",
"autoTag": true,
"noteFormat": {
"includeTimestamp": true,
"includeContext": true,
"template": "default"
}
}
配置选项
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
vaultPath |
string | - | 必需.通往黑曜石金库的路径 |
defaultFolder |
string | “MCP Notes” | 新笔记的默认文件夹 |
dateFormat |
string | “YYYY-MM-DD” | 时间戳的日期格式 |
autoTag |
boolean | true | 自动添加默认标签 |
noteFormat.includeTimestamp |
boolean | true | 包含创建时间戳 |
noteFormat.includeContext |
boolean | true | 包含上下文部分 |
noteFormat.template |
string | “默认” | 注意要使用的模板 |
用法
AI助手
使用自然语言命令，如：
- “从我们关于机器学习的对话中创建一个注释，只突出关键点”
- “在我的保险库中搜索有关web开发的笔记”
- “向我展示关于项目规划的注释内容”
- “查找所有标记为‘python’或‘programming’的笔记”
可用工具
1. create_conversation_note
根据对话内容创建结构化笔记。
参数：
topic（string，必填）-对话的主要主题highlights（数组，必填）-对话中的要点列表tags（数组，可选）-用于对注释进行分类的其他标签folder（字符串，可选）-vault中用于保存注释的特定文件夹context（字符串，可选）-有关对话的其他上下文
例子：
{
"topic": "Machine Learning Fundamentals",
"highlights": [
"Supervised learning requires labeled data",
"Neural networks mimic brain structure",
"Feature engineering is crucial for model performance"
],
"tags": ["ml", "ai", "fundamentals"],
"folder": "Learning/ML"
}
2. search_notes
在vault中搜索现有笔记。
参数：
query（字符串，可选）-在笔记内容中搜索的文本tags（数组，可选）-用于过滤笔记的标签limit（数字，可选）-最大结果数（默认值：10）
例子：
{
"query": "neural networks",
"tags": ["ml", "deep-learning"],
"limit": 5
}
3. get_note_structure
检索特定注释的详细信息。
参数：
note_path（字符串，必填）-金库中钞票的相对路径
例子：
{
"note_path": "MCP Notes/machine-learning-fundamentals.md"
}
备注格式
生成的笔记遵循以下结构化格式：
---
created: "2025-11-16"
context: "AI Conversation"
tags: ["machine-learning", "mcp", "ai"]
---
# Machine Learning Fundamentals
## Key Points
1. Supervervised learning requires labeled data
2. Neural networks mimic brain structure
3. Feature engineering is crucial for model performance
## Discussion Context
Additional context about the learning session and topics covered.
---
*Generated via MCP on 11/16/2025 14:30*
MCP客户端设置
将此服务器添加到您的MCP客户端配置中（例如，Claude Desktop）：
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/server.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
}
}
}
}
发展
# Development with watch mode
npm run dev
# Type checking
npm run typecheck
# Linting
npm run lint
# Build for production
npm run build
# Start the server
npm start
项目结构
obsidian-mcp/
├── src/
│ ├── server.ts # Main MCP server
│ ├── obsidian/
│ │ ├── vault.ts # Vault management
│ │ ├── note.ts # Note operations
│ │ └── formatter.ts # Content formatting
│ └── types/
│ └── index.ts # TypeScript types
├── config/
│ └── default.json # Default configuration
├── dist/ # Compiled JavaScript
├── node_modules/ # Dependencies
├── package.json # Project metadata
├── tsconfig.json # TypeScript configuration
└── README.md
故障排除
常见问题
-
“未配置OBSIDIAN_VAULT_PATH”
- 确保环境变量已设置或更新config/default.json
-
“未找到保险库”
- 验证vault路径是否正确且可访问
- 检查文件权限
-
“权限被拒绝”
- 确保服务器具有对vault的读/写访问权限
- 检查文件夹权限
调试模式
通过设置启用调试日志记录：
export DEBUG=obsidian-mcp:*
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 运行测试和梳理
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
