使用说明
黑曜石语义mcp
黑曜石金库的语义搜索MCP服务器。使用Gemini嵌入和ChromaDB对vault内容进行索引，然后将其作为用于Claude Code（或任何MCP客户端）的MCP工具公开。
特性
- 多文件类型支持：Markdown、Canvas、PDF、图像、音频、视频
- 语义搜索：由Gemini嵌入支持的自然语言查询
- 增量索引：SQLite mtime跟踪--仅重新索引更改的文件
- 文件监视器：可选的基于监视器的vault更改自动重新索引
- 5个MCP工具：搜索、状态、重新索引、获取文件、列出文件
支持的文件类型
| 类型 | 扩展 |
|---|---|
| 文本 | .md, .canvas |
.pdf |
|
| 图片 | .png, .jpg, .jpeg, .webp, .heic |
| 音频 | .mp3, .m4a, .wav |
| 视频 | .mp4, .mov |
设置
需要Python 3.11+和 紫外线.
# Clone and install
git clone <repo-url> obsidian-semantic-mcp
cd obsidian-semantic-mcp
uv sync
设置环境变量：
export GEMINI_API_KEY="your-gemini-api-key"
export VAULT_PATH="/path/to/your/obsidian/vault"
用法
为您的保险库建立索引
# Full vault ingestion
uv run python server.py ingest --vault /path/to/vault
# Single file
uv run python server.py ingest --file /path/to/vault/note.md
以MCP服务器运行
uv run python server.py
Claude代码配置
添加到您的 .claude/mcp.json:
{
"mcpServers": {
"obsidian-semantic": {
"command": "uv",
"args": ["run", "--project", "/path/to/obsidian-semantic-mcp", "python", "server.py"],
"env": {
"GEMINI_API_KEY": "your-key",
"VAULT_PATH": "/path/to/vault"
}
}
}
}
MCP工具
vault_semantic_search
使用自然语言语义相似性搜索保险库。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
query |
str |
必填 | 自然语言搜索查询 |
n_results |
int |
10 |
结果数量（最多50个） |
vault_index_status
获取当前索引状态：总块数、文件类型计数、跟踪器统计信息。
vault_reindex
重新索引整个vault或特定文件。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
file_path |
str |
None |
要重新索引的特定文件。如果省略，请重新索引整个vault。 |
vault_get_file
检索vault文件的完整内容。返回以下内容的原始文本 .md/.canvas，为PDF提取文本，为二进制文件提取元数据。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
file_path |
str |
必需 | 文件路径 |
vault_list_files
使用可选目录和类型过滤器列出vault中的文件。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
directory |
str |
None |
相对于vault根目录的子目录 |
file_type |
str |
None |
筛选器： "text", "pdf", "image", "audio", "video" |
环境变量
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
GEMINI_API_KEY |
是 | - | Google Gemini API密钥 |
VAULT_PATH |
是 | -- | 通往黑曜石拱顶的绝对路径 |
CHROMA_PERSIST_DIR |
没有 | ~/.obsidian-mcp/chroma |
ChromaDB存储位置 |
WATCH_VAULT |
没有 | true |
启用文件监视器以自动重新索引 |
