使用说明

保险库mcp

将任何文件夹转换为可搜索的人工智能知识库，通过以下方式公开主控程序.

把它指向一个目录。它嵌入了所有内容——降价、PDF、图像、音频、视频。从Claude Desktop、Claude Code或任何MCP客户端搜索。

为什么存在

现有的RAG工具要么想成为事实的来源（将文件复制到自己的存储中），要么只处理markdown。vault-mcp将您的文件夹视为唯一的事实来源。嵌入索引是派生状态——删除它并在几秒钟内从头开始重建。Git处理版本控制。您的AI助手可以直接修改文件。vault-mcp只是让它们可以搜索。

专为个人知识库、项目文档、研究档案而构建——任何有混合格式文件文件夹并希望对其进行语义搜索的地方。

特性

多格式提取 --Markdown、PDF、DOCX、PPTX、图像（OCR）、音频/视频（耳语转录）
航向感知标记分块 --按标题拆分，保留面包屑上下文(# Strategy > ## Vision > ### North Star)，合并小部分，拆分大部分
块级重复数据删除 --只重新嵌入实际更改的块。编辑40KB文档中的一个段落？一个API调用，而不是80
文件重命名检测 --移动文件？零重嵌入。按内容哈希匹配
三层跳过层次结构 --mtime不变→ 完全跳过。内容不变→ 跳过提取。块不变→ 跳过嵌入
现场观看 --基于监视器的文件监视器，具有2秒去抖动功能。更改会在几秒钟内出现在搜索中
远程MCP传输 --流式HTTP（默认）、SSE或stdio。随时随地连接
SQLite+SQLite-vec --单文件数据库，无外部服务。约50MB内存占用

快速入门

pip install vault-mcp

设置您的OpenAI API密钥（用于 text-embedding-3-small 嵌入）：

export OPENAI_API_KEY=sk-...

为文件夹建立索引并启动服务器：

export VAULT_PATH=/path/to/your/folder

# First-time index
vault-mcp reindex

# Start MCP server (streamable-http on port 8100)
vault-mcp serve --watch

从克劳德桌面连接

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "vault": {
      "url": "http://localhost:8100/mcp"
    }
  }
}

对于具有身份验证的远程服务器（请参见远程部署):

{
  "mcpServers": {
    "vault": {
      "type": "http",
      "url": "https://your-server/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

从克劳德代码连接

添加 .mcp.json 或设置：

{
  "mcpServers": {
    "vault": {
      "url": "http://your-server:8100/mcp"
    }
  }
}

通过stdio连接（仅限本地）

{
  "mcpServers": {
    "vault": {
      "command": "vault-mcp",
      "args": ["serve", "--transport", "stdio", "--watch"],
      "env": {
        "VAULT_PATH": "/path/to/your/folder",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

MCP工具

工具	目的
`search`	对保险库进行语义搜索
`reindex`	重新嵌入更改的文件
`stats`	指数统计
`write`	编写一个文件，并可选择git commit

网络钩子

vault-mcp可以从外部服务接收webhook，并将捕获直接写入vault。

端点	方法	描述
`/webhook/voicenotes`	POST	接收语音笔记转录

语音笔记webhook

手柄 recording.created, recording.updated，以及 recording.deleted 事件。将转录内容写入 captures/inbox/YYYY/MM/YYYY-MM-DD-{slug}.md 与frontmatter。文件查看器会在几秒钟内自动为新文件建立索引。

认证： 集 WEBHOOK_SECRET env var.作为查询参数传递： /webhook/voicenotes?secret=xxx （VoiceNotes不支持自定义标头）。如果 WEBHOOK_SECRET 如果未设置，则接受所有请求。

例子：

curl -X POST 'http://localhost:8100/webhook/voicenotes?secret=xxx' \
  -H 'Content-Type: application/json' \
  -d '{"event":"recording.created","timestamp":"2026-03-01T10:00:00Z","data":{"id":"abc-123","title":"Morning thoughts","transcript":"Need to ship the onboarding flow this week."}}'

`search(query, top_k?, path_filter?)`

在您的保险库中进行语义搜索。

query: "north star vision"
top_k: 5
path_filter: "strategy/"  # optional — scope to subdirectory

返回具有文本、文件路径、标题面包屑和相关性得分的匹配块。

`reindex(path?)`

重新嵌入更改的文件。如果没有路径，将对整个vault进行索引（跳过未更改的文件）。使用路径，强制重新索引该文件或目录。

`stats()`

返回索引文件计数、块计数、上次索引时间、vault路径和嵌入模型。

`write(path, content, commit_message?)`

将文件写入vault，并可选择git commit。调用者处理分类和frontmatter——vault-mcp只是写入字节和提交。

path: "captures/saturn/2026/03/ai-architecture-insight.md"
content: "---\nplanet: saturn\nsource: slack\n---\n\nBreakthrough on embedding context..."
commit_message: "capture(saturn): AI architecture insight from Slack"  # optional

退货 { status, path, relative_path, committed?, commit_hash? }。vault外部的路径遍历被拒绝。没有git推送——这是单独处理的。

命令行界面

# Index the vault (only changed files)
vault-mcp reindex

# Force re-embed everything
vault-mcp reindex --force

# Index a specific subdirectory
vault-mcp reindex captures/

# Start MCP server
vault-mcp serve                          # streamable-http on 0.0.0.0:8100
vault-mcp serve --transport stdio        # stdio for local MCP
vault-mcp serve --port 9000              # custom port
vault-mcp serve --watch                  # watch for file changes

# Check index stats
vault-mcp stats

运作原理

Your Folder (git-backed)
  │
  ├── .md, .pdf, .docx, .png, .mp4, ...
  │
  ▼
Extractor
  │  Markdown → passthrough
  │  PDF/DOCX → Kreuzberg
  │  Images → Kreuzberg OCR (Tesseract)
  │  Audio/Video → OpenAI Whisper
  │
  ▼
Chunker
  │  Markdown → heading-aware splitting (512 token chunks)
  │  Everything else → paragraph grouping
  │  Overlap: last 1-2 sentences between chunks
  │
  ▼
Embedder
  │  OpenAI text-embedding-3-small (1536 dims)
  │  Batched, with retry/backoff
  │  Chunk-level dedup via SHA-256 hash
  │
  ▼
SQLite + sqlite-vec
  │  chunks: text, embedding, file_path, heading_path
  │  files: path, mtime, content_hash
  │
  ▼
MCP Server (FastMCP)
     search / reindex / stats

远程部署

vault-mcp没有内置身份验证。对于远程访问，请在nginx后面使用承载令牌auth运行它：

仅绑定到本地主机 并使用可流式传输的http（默认）：

vault-mcp serve --watch --host 127.0.0.1 --port 8100

添加nginx反向代理 使用承载令牌验证：

server {
    listen 443 ssl;
    server_name vault-mcp.example.com;

    # SSL certs (e.g. Let's Encrypt)
    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    location / {
        if ($http_authorization != "Bearer YOUR_SECRET_TOKEN") {
            return 401 "Unauthorized";
        }

        proxy_pass http://127.0.0.1:8100;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

可选：systemd用户服务 对于自动重启：

# ~/.config/systemd/user/vault-mcp.service
[Unit]
Description=vault-mcp
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/vault-mcp
Environment=OPENAI_API_KEY=sk-...
Environment=VAULT_PATH=/path/to/your/vault
ExecStart=/path/to/vault-mcp serve --watch --host 127.0.0.1 --port 8100
Restart=on-failure

[Install]
WantedBy=default.target

systemctl --user enable --now vault-mcp

配置

环境变量	默认值	描述
`OPENAI_API_KEY`	（必需）	用于嵌入的OpenAI API密钥
`VAULT_PATH`	`.` （当前目录）	要索引的文件夹的路径
`VAULT_DB_PATH`	`~/.vault-mcp/index.db`	SQLite数据库位置
`WEBHOOK_SECRET`	（可选）	webhook身份验证的共享密钥（查询参数）

支持格式

格式	方法	注释
`.md`, `.txt`, `.yaml`, `.json`, `.toml`	直接阅读	Markdown实现了标题感知分块
`.pdf`, `.docx`, `.pptx`, `.xlsx`, `.odt`, `.rtf`, `.epub`, `.html`	Kreuzberg	异步提取
`.png`, `.jpg`, `.gif`, `.bmp`, `.tiff`, `.webp`	克罗伊茨贝格OCR	Tesseract后端
`.mp3`, `.mp4`, `.m4a`, `.wav`, `.ogg`, `.flac`, `.webm`, `.avi`, `.mkv`, `.mov`	OpenAI Whisper	时间窗口块

依赖项

FastMCP --MCP服务器框架
克罗伊茨贝格 --文档/图像文本提取
开放人工智能 --嵌入+耳语转录
sqlite-vc --SQLite中的矢量搜索
看门狗 --文件系统监控
令牌。 --代币计数

许可证

麻省理工学院

使用说明

保险库mcp

为什么存在

特性

快速入门

从克劳德桌面连接

从克劳德代码连接

通过stdio连接（仅限本地）

MCP工具

网络钩子

语音笔记webhook

search(query, top_k?, path_filter?)

reindex(path?)

stats()

write(path, content, commit_message?)

命令行界面

运作原理

远程部署

配置

支持格式

依赖项

许可证

相关 MCP

AI持久记忆服务器

多格式文档转Markdown转换器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

文档格式转换服务

网页内容抓取服务器

`search(query, top_k?, path_filter?)`

`reindex(path?)`

`stats()`

`write(path, content, commit_message?)`