Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zvec-ai/zvec-mcp-server

Zvec Official MCP Server
https://github.com/zvec-ai/zvec-mcp-server

ai mcp-server vector-search

Last synced: about 2 months ago
JSON representation

Zvec Official MCP Server

Awesome Lists containing this project

README 

          
# Zvec MCP Server



A Model Context Protocol (MCP) server for [Zvec](https://github.com/alibaba/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



```bash

# Using uv (recommended)

uv pip install zvec-mcp-server



# Or using pip

pip install zvec-mcp-server

```



### Install from Source



```bash

# 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



```bash

# 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`):



```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):



```json

{

  "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



```python

# 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.



```bash

# 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](https://github.com/alibaba/zvec)

- [Zvec Documentation](https://zvec.org/)

- [MCP Specification](https://modelcontextprotocol.io/)

- [FastMCP Documentation](https://github.com/modelcontextprotocol/python-sdk)



## License



[Apache 2.0](LICENSE)



## Contributing



Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.



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