vectorai-mcp-server

将 Actian VectorAI DB 作为 MCP 服务器暴露出来，让 Claude（Desktop 或 Code）和 Cursor 可以通过纯自然语言工具调用来创建集合、摄入文档并运行语义搜索——无需手动进行向量运算，也无需编写客户端嵌入代码。

所有嵌入都在服务端通过 sentence-transformers（all-MiniLM-L6-v2，384 维）完成。每个工具都接收和返回纯字符串/JSON；原始向量永远不会跨过 MCP 边界。

这是一个为黑客松演讲准备的演示项目，刻意保持简单，不包含认证或多租户功能。

前提条件

• Docker（用于运行 VectorAI DB）

• Python 3.10+

Related MCP server: Qdrant MCP Server

1. 启动 VectorAI DB

在项目根目录下：

docker-compose up -d

这会启动 actian/vectorai:latest，并暴露以下端口：

• 6573 - REST API

• 6574 - gRPC API（供 Python 客户端使用）

• 6575 - 本地 UI

数据在重启后会持久化在 ./local_data 中。使用以下命令检查它是否正在运行：

docker ps
docker logs vectorai

2. 安装依赖项

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

如果你想要覆盖默认的 VectorAI DB URL，可以选择将 .env.example 复制为 .env：

cp .env.example .env

3. 使用演示脚本验证连接

在接入任何 MCP 客户端之前，先确认 VectorAI DB 和嵌入模型都能正常工作：

python examples/demo.py

该脚本会创建一个 hackathon_demo 集合，嵌入并摄入六份示例 FAQ 文档，运行查询 "when do we submit our project"，并打印最匹配的结果。首次运行会下载 all-MiniLM-L6-v2 模型（约 90 MB），因此可能需要一分钟。

Windows 注意事项： sentence-transformers 会引入 torch，它自带一些嵌套很深的许可证文件。如果 pip install 因 WinError 206（"filename or extension is too long"）而失败，可以启用长路径（Settings → System → About → Advanced system settings，或将 HKLM\SYSTEM\CurrentControlSet\Control\FileSystem 下的 LongPathsEnabled 设置为 1 并重启），也可以将项目克隆到更靠近驱动器根目录的位置（例如 C:\dev\vectorai-mcp-server）以缩短路径。

4. 注册 MCP 服务器

Claude Desktop

编辑你的 claude_desktop_config.json（位置因操作系统而异），并在 mcpServers 下添加一个 vectorai-db 条目。请使用你的 Python 可执行文件和 server.py 的绝对路径：

{
  "mcpServers": {
    "vectorai-db": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/vectorai-mcp-server/server.py"],
      "env": {
        "VECTORAI_URL": "localhost:6574"
      }
    }
  }
}

在 Windows 上，command 会类似于 C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe。

保存后重启 Claude Desktop。你应该会看到 vectorai-db 被列为一个已连接的 MCP 服务器（寻找 🔌/工具图标）。

Cursor

在项目中创建或编辑 .cursor/mcp.json（或使用 ~/.cursor/mcp.json 作为全局配置），然后添加相同的服务器条目：

{
  "mcpServers": {
    "vectorai-db": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/vectorai-mcp-server/server.py"],
      "env": {
        "VECTORAI_URL": "localhost:6574"
      }
    }
  }
}

重新加载 Cursor（或在 Settings → MCP 中关闭/打开 MCP 服务器）以让更改生效。你应该会看到 vectorai-db 及其六个工具（create_collection、ingest_documents、search、list_collections、get_collection_info、delete_collection）被列为可用状态。

5. 试一试

在 VectorAI DB 运行且 MCP 服务器已连接的情况下，向 Claude 或 Cursor 输入类似这样的提示词：

• "创建一个名为 notes 的集合。"

• "把关于我们黑客松的三条信息添加到 notes：黑客松周六上午 9 点开始，提交截止时间是周日上午 9 点，一等奖为 2,000 美元。"

• "奖品截止时间是什么？"

• "在 notes 中搜索任何与评审标准相关的内容。"

• "列出数据库中的所有集合。"

• "notes 中有多少文档？"

• "删除 notes 集合。"

助手会代表你调用 create_collection、ingest_documents、search、list_collections、get_collection_info 和 delete_collection，并在后台使用 all-MiniLM-L6-v2 对所有内容进行嵌入。

项目结构

vectorai-mcp-server/
├── server.py            # The MCP server (FastMCP, stdio transport)
├── requirements.txt
├── docker-compose.yml    # Runs actian/vectorai:latest
├── .env.example
├── examples/
│   └── demo.py           # Standalone connection check, no MCP client needed
└── README.md