Zvec MCP Server

A Model Context Protocol (MCP) server for Zvec, a high-performance embedded vector database by Alibaba.

This MCP server enables LLMs to interact with Zvec vector database through well-designed tools. It provides comprehensive functionality for:

• Collection Management: Create, open, and manage vector database collections
• Document Operations: Insert, update, delete, and fetch documents with full CRUD support
• Vector Search: Single-vector and multi-vector similarity search with re-ranking
• Index Management: Create and manage vector indexes (HNSW, IVF, FLAT) for fast retrieval
• AI Embedding: OpenAI-powered dense embedding with automatic text-to-vector conversion

• 🚀 17 Comprehensive Tools: Full API coverage for common vector database operations
• 🤖 AI-Powered Embedding: Built-in OpenAI embedding for semantic search
• 📊 Multiple Response Formats: Support both JSON and Markdown output formats
• 🔍 Multi-Vector Search: Combine multiple embeddings with advanced re-ranking
• 🎯 Hybrid Search: Combine vector similarity with scalar filters
• 🛡️ Type Safety: Full Pydantic v2 validation for all inputs
• 📝 Rich Documentation: Detailed tool descriptions with examples

• Python 3.10 - 3.14
• Supported platforms: Linux (x86_64, ARM64), macOS (ARM64), Windows (x86_64)

# Using uv (recommended)
uv pip install zvec-mcp-server
# Or using pip
pip install zvec-mcp-server

# Clone the repository
git clone https://github.com/zvec-ai/zvec-mcp-server.git
cd zvec-mcp-server
# Using uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
# Or using pip
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Using the installed package
python -m zvec_mcp
# Or with uv
uv run python -m zvec_mcp
# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m zvec_mcp

Add to your IDE's MCP configuration file:

Qoder MCP Config (~/.qoder/mcp.json or ~/.config/qoder/mcp.json):

{
 "mcpServers": {
 "zvec-mcp": {
 "command": "uvx",
 "args": ["zvec-mcp-server"],
 "env": {
 "OPENAI_API_KEY": "your-api-key",
 "OPENAI_BASE_URL": "https://api.openai.com/v1",
 "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small"
 }
 }
 }
}

Claude Desktop Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
 "mcpServers": {
 "zvec-mcp": {
 "command": "uvx",
 "args": ["zvec-mcp-server"],
 "env": {
 "OPENAI_API_KEY": "your-api-key"
 }
 }
 }
}

Environment Variables:

• OPENAI_API_KEY (required): OpenAI API key for embedding generation
• OPENAI_BASE_URL (optional): Custom API endpoint (e.g., for DashScope)
• OPENAI_EMBEDDING_MODEL (optional): Model name, default is text-embedding-3-small

# 1. Create and open a collection
create_and_open_collection({
 "path": "./my_vectors",
 "collection_name": "docs_col",
 "vector_fields": [
 {
 "name": "embedding",
 "data_type": "VECTOR_FP32",
 "dimension": 1536
 }
 ],
 "scalar_fields": [
 {
 "name": "title",
 "data_type": "STRING",
 "nullable": False
 }
 ]
})
# 2. Insert documents with auto-generated embeddings (requires OPENAI_API_KEY)
embedding_write({
 "collection_name": "docs_col",
 "field_name": "embedding",
 "documents": [
 {
 "id": "doc1",
 "text": "This is a sample document about machine learning.",
 "fields": {"title": "ML Introduction"}
 }
 ]
})
# 3. Semantic search with natural language query
embedding_search({
 "collection_name": "docs_col",
 "field_name": "embedding",
 "query_text": "artificial intelligence and neural networks",
 "topk": 10
})

• create_and_open_collection - Create new collection with schema and auto-create indexes
• open_collection - Open existing collection into session cache
• get_collection_info - Get schema and statistics
• destroy_collection - Permanently delete collection

• insert_documents - Insert new documents (fail if exists)
• upsert_documents - Insert or update documents
• update_documents - Update existing documents
• delete_documents - Delete documents by ID
• fetch_documents - Retrieve documents by ID

• vector_query - Single-vector similarity search with optional filtering
• multi_vector_query - Multi-vector search with re-ranking (Weighted/RRF)

• create_index - Create vector index (HNSW/IVF/FLAT) or scalar index (INVERT)
• drop_index - Remove index from field
• optimize_collection - Optimize collection for better performance

• generate_dense_embedding - Generate embedding for text using OpenAI API
• embedding_write - Auto-embed text documents and upsert to collection
• embedding_search - Natural language semantic search with auto-embedding

• VECTOR_FP32, VECTOR_FP64, VECTOR_FP16 - Dense float vectors
• VECTOR_INT8 - Dense integer vectors
• SPARSE_VECTOR_FP32, SPARSE_VECTOR_FP16 - Sparse vectors (Dict[int, float])

• INT32, INT64, UINT32, UINT64 - Integer types
• FLOAT, DOUBLE - Floating point types
• STRING, BOOL - Text and boolean

Vector Indexes:

• HNSW - Hierarchical Navigable Small World (recommended for most cases)
• IVF - Inverted File Index (good for large datasets)
• FLAT - Brute-force exact search (small datasets)

Scalar Indexes:

• INVERT - Inverted index for scalar fields with optional range optimization

• COSINE - Cosine similarity
• IP - Inner product
• L2 - Euclidean distance

• WEIGHTED - Weighted score fusion with custom weights per field
• RRF - Reciprocal Rank Fusion (rank-based fusion)

zvec-mcp-server/
├── src/
│ └── zvec_mcp/
│ ├── __init__.py # Package entry point
│ ├── server.py # MCP server implementation (17 tools)
│ ├── schemas.py # Pydantic input validation models
│ ├── types.py # Enums and type definitions
│ └── utils.py # Helper functions and formatters
├── tests/
│ └── test_server.py # Pytest test suite
├── pyproject.toml # Project configuration
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
└── LICENSE # Apache 2.0 License

The server exposes two MCP resources for introspection:

• zvec://collections - List all opened collections in the current session
• zvec://collection/{collection_name} - Get detailed schema and stats for a specific collection

All tools provide clear, actionable error messages:

• Resource not found errors with suggestions
• Validation errors from Pydantic v2
• Zvec API errors with context

Tools support two output formats:

• JSON: Structured data for programmatic processing
• Markdown: Human-readable formatted text with headers and lists

The project includes a comprehensive pytest test suite with 21 test cases covering all functionality.

# Install dev dependencies (includes pytest and pytest-asyncio)
uv pip install -e ".[dev]"
# Run all tests
pytest tests/test_server.py -v

• Zvec GitHub
• Zvec Documentation
• MCP Specification
• FastMCP Documentation

Apache 2.0

Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.