vectorai-mcp-server

Expose Actian VectorAI DB as an MCP server, so Claude (Desktop or Code) and Cursor can create collections, ingest documents, and run semantic search through plain natural-language tool calls - no manual vector math, no client-side embedding code.

All embedding happens server-side with sentence-transformers (all-MiniLM-L6-v2, 384 dimensions). Every tool takes and returns plain strings/JSON; raw vectors never cross the MCP boundary.

This is a demo project for a hackathon talk, kept intentionally simple, with no auth or multi-tenancy.

Prerequisites

• Docker (to run VectorAI DB)

• Python 3.10+

Related MCP server: Qdrant MCP Server

1. Start VectorAI DB

From the project root:

docker-compose up -d

This starts actian/vectorai:latest, exposing:

• 6573 - REST API

• 6574 - gRPC API (used by the Python client)

• 6575 - Local UI

Data persists in ./local_data across restarts. Check it's running with:

docker ps
docker logs vectorai

2. Install dependencies

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

Optionally copy .env.example to .env if you want to override the default VectorAI DB URL:

cp .env.example .env

3. Verify the connection with the demo script

Before wiring up any MCP client, sanity-check that VectorAI DB and the embedding model both work:

python examples/demo.py

This creates a hackathon_demo collection, embeds and ingests six sample FAQ documents, runs the query "when do we submit our project", and prints the top match. The first run downloads the all-MiniLM-L6-v2 model (~90 MB), so it may take a minute.

Windows note: sentence-transformers pulls in torch, which ships some deeply nested license files. If pip install fails with WinError 206 ("filename or extension is too long"), either enable long paths (Settings → System → About → Advanced system settings, or set LongPathsEnabled under HKLM\SYSTEM\CurrentControlSet\Control\FileSystem to 1 and reboot) or clone the project closer to your drive root (e.g. C:\dev\vectorai-mcp-server) to shorten the path.

4. Register the MCP server

Claude Desktop

Edit your claude_desktop_config.json (location varies by OS) and add a vectorai-db entry under mcpServers. Use absolute paths to your Python executable and to 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"
      }
    }
  }
}

On Windows, command would look like C:\\absolute\\path\\to\\vectorai-mcp-server\\.venv\\Scripts\\python.exe.

Restart Claude Desktop after saving. You should see vectorai-db listed as a connected MCP server (look for the 🔌/tools icon).

Cursor

Create or edit .cursor/mcp.json in the project (or ~/.cursor/mcp.json for a global config) and add the same server entry:

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

Reload Cursor (or toggle the MCP server off/on in Settings → MCP) to pick up the change. You should see vectorai-db and its six tools (create_collection, ingest_documents, search, list_collections, get_collection_info, delete_collection) listed as available.

5. Try it

With VectorAI DB running and the MCP server connected, type prompts like these into Claude or Cursor:

• "Create a collection called notes."

• "Add these three facts about our hackathon to notes: the hackathon starts Saturday at 9am, submissions close Sunday at 9am, and first prize is $2,000."

• "What's the prize deadline?"

• "Search notes for anything about judging criteria."

• "List all the collections in the database."

• "How many documents are in notes?"

• "Delete the notes collection."

The assistant will call create_collection, ingest_documents, search, list_collections, get_collection_info, and delete_collection on your behalf, embedding everything with all-MiniLM-L6-v2 behind the scenes.

Project structure

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