Zvec MCP Server

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

Overview

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

Features

• 🚀 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

Installation

Requirements

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

Install from PyPI

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

# Or using pip
pip install zvec-mcp-server

Install from Source

# 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]"

Quick Start

Running the Server

# 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

IDE Integration (Qoder/Cursor/Claude Desktop)

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

Basic Usage Example

# 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
})

Available Tools

Collection Management (4 tools)

• 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

Document Operations (5 tools)

• 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 Search (2 tools)

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

Index Management (3 tools)

• 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

AI Embedding (3 tools)

• 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

Tool Details

Vector Data Types

• 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])

Scalar Data Types

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

Index Types

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

Distance Metrics

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

Re-ranking Strategies (Multi-Vector Query)

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

Architecture

Modular Structure

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

MCP Resources

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

Error Handling

All tools provide clear, actionable error messages:

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

Response Formats

Tools support two output formats:

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

Development

Running Tests

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

References

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

License

Apache 2.0

Contributing

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.