内容
# DuckVault-MCP
DuckVault-MCP 是一个 MCP（模型上下文协议）服务器，利用 DuckDB 和向量搜索为您的 Obsidian 知识库提供 RAG（检索增强生成）系统。
## 功能特点
- **本地向量搜索**：使用 `sentence-transformers`（`intfloat/multilingual-e5-small`）进行本地嵌入。
- **Obsidian URI 链接**：从搜索结果直接链接到 Obsidian 笔记。
- **增量索引**：使用 MD5 哈希仅更新修改的文件。
- **实时监控**：使用 `watchdog` 在编辑笔记时索引更改。
- **进度指示器**：为大型知识库显示初始索引时的进度条。
- **快速搜索**：利用 DuckDB 和 `vss` 扩展以及 HNSW 索引，实现毫秒级检索。
- **MCP 兼容**：与 Claude Code 或 Cursor 等 AI 代理无缝协作。
## 安装
```bash
# 使用 uv（推荐）
uv tool install mcp-duckvault
# 直接从 GitHub
uv tool install git+https://github.com/caron14/mcp-obsidian-duckdb.git
# 从 PyPI（发布后）
pip install mcp-duckvault
```
## 使用
将 MCP 服务器指向您的 Obsidian 知识库：
```bash
duckvault /path/to/your/obsidian/vault
```
**选项**
- `--db-path`：DuckDB 文件路径（默认值：`~/.duckvault/vault.db`）。
- `--sync-only`：执行知识库的完整同步并退出。
- `-v, --verbose`：启用详细日志记录。
### 命令行示例
**基本用法：**
```bash
duckvault /path/to/your/obsidian/vault
```
**自定义数据库路径：**
指定 DuckDB 索引文件的自定义位置。
```bash
duckvault /path/to/your/obsidian/vault --db-path ./vault_index.db
```
**仅同步（无界面模式）：**
索引所有文件并退出，不启动 MCP 服务器。
```bash
duckvault /path/to/your/obsidian/vault --sync-only
```
### AI 代理查询示例
连接后，您可以通过 AI 代理使用自然语言与您的知识库交互：
- **语义搜索**： "查找关于机器学习项目的笔记并列出提到的关键概念。"
- **过滤搜索**： "搜索带有 #work 标签的 'meeting' 笔记并总结行动项。"
- **保持更新**： "我最近 3 天内处理过哪些最重要的笔记？"
- **跨笔记分析**： "根据我最近关于 'React' 的笔记，我对 Hooks 的理解有何演变？"
### 排除文件（`.vaultignore`）
要排除特定文件或目录被索引，请在 Obsidian 知识库的根目录创建 `.vaultignore` 文件。语法类似于 `.gitignore`。
默认情况下，`.obsidian` 和 `.trash` 始终被排除。
示例 `.vaultignore`：
```text
# 排除特定文件夹
private/
drafts/
# 排除特定文件类型
*.tmp
*.log
```
## AI 代理注册
该服务器符合 MCP（模型上下文协议）并可在通过 `uv tool install` 或 `pip install` 安装后与以下代理一起使用。
**注意**：请将知识库路径指定为**绝对路径**（例如 `/Users/username/Documents/MyVault`）。
### Claude Desktop (macOS)
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"duckvault": {
"command": "duckvault",
"args": [
"/absolute/path/to/your/obsidian/vault"
]
}
}
}
```
### Claude Code
您可以使用命令行（推荐）或编辑配置文件永久添加服务器。
**使用命令行：**
```bash
claude mcp add duckvault -- duckvault /absolute/path/to/your/obsidian/vault
```
**编辑配置文件：**
将以下内容添加到 `~/.claude.json`：
```json
{
"mcpServers": {
"duckvault": {
"command": "duckvault",
"args": [
"/absolute/path/to/your/obsidian/vault"
]
}
}
}
```
### Gemini CLI
您可以使用命令行（推荐）或编辑配置文件永久添加服务器。
**使用命令行：**
```bash
gemini mcp add duckvault --scope user duckvault /absolute/path/to/your/obsidian/vault
```
**编辑配置文件：**
将以下内容添加到配置文件（`~/.gemini/settings.json`）的 `mcpServers` 部分。
```json
{
"mcpServers": {
"duckvault": {
"command": "duckvault",
"args": [
"/absolute/path/to/your/obsidian/vault"
]
}
}
}
```
### GitHub Copilot（在命令行中）
GitHub Copilot 在命令行中支持 MCP 服务器。您可以使用交互式 `/mcp` 命令或编辑配置文件添加服务器。
**使用命令行：**
1. 启动交互式会话：`copilot`（或 `gh copilot chat`）。
2. 运行 `/mcp add` 命令并按照提示进行操作。
**编辑配置文件：**
将以下内容添加到 `~/.copilot/mcp-config.json`：
```json
{
"mcpServers": {
"duckvault": {
"command": "duckvault",
"args": [
"/absolute/path/to/your/obsidian/vault"
]
}
}
}
```
## MCP 工具
服务器向 AI 代理公开以下工具：
1. `search_notes(query: str, tag: Optional[str] = None, limit: int = 5)`：使用自然语言搜索相关笔记。
2. `list_recent_notes(days: int = 7)`：列出最近更新的笔记。
## 许可证
MIT
