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 컬렉션을 만들고, 6개의 샘플 FAQ 문서를 임베딩하여 수집하고, "when do we submit our project" 쿼리를 실행한 후 최상위 일치 항목을 출력합니다. 첫 실행 시 all-MiniLM-L6-v2 모델(약 90MB)을 다운로드하므로 1분 정도 걸릴 수 있습니다.

Windows 참고: sentence-transformers는 torch를 끌어오는데, torch에는 깊게 중첩된 라이선스 파일이 포함되어 있습니다. pip install이 WinError 206("파일 이름 또는 확장명이 너무 깁니다")으로 실패하면, 긴 경로를 활성화(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을 편집하고(위치는 OS에 따라 다름) 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을 다시 시작하세요. 연결된 MCP 서버로 vectorai-db가 표시되어야 합니다(🔌/도구 아이콘을 찾아보세요).

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를 다시 로드하세요(또는 설정 → 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시이며, 1등 상금은 $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