Which integrations are available for this server?

Provides AI-powered embedding generation using OpenAI's API for semantic search and text-to-vector conversion in Zvec vector database.

How do I use zvec-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zvec-mcp-server Create a collection named 'products' with a 1536-dim vector field and a title scalar field." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

zvec-mcp-server

Official

by zvec-ai

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

Related MCP server: Milvus MCP Server

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

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.

Available Tools

17 tools

create_and_open_collectionA

Create a new Zvec collection and open it for use.

This tool creates a new vector database collection at the specified path with the given schema definition. The collection is automatically opened and cached for subsequent operations. Use this when you need to initialize a new vector database.

Args: params (CreateCollectionInput): Validated input parameters containing: - path (str): Filesystem path where collection will be created (e.g., './my_vectors') - collection_name (str): Name of the collection (also used as unique session key) - vector_fields (List[VectorFieldInput]): Vector field definitions (required, min 1); each field may include an optional index_param to auto-create its index - scalar_fields (Optional[List[ScalarFieldInput]]): Scalar field definitions; each field may also include an optional index_param

Returns: str: Success message with collection details or error message

Examples: - Use when: "Create a new collection for storing document embeddings" - Use when: "Initialize a vector database at ./embeddings with 768-dim vectors" - Don't use when: Collection already exists (use open_collection instead)

Inputs: params (required). Returns: result

create_indexA

Create an index on a field to accelerate queries.

Use HnswIndexParamInput / FlatIndexParamInput / IVFIndexParamInput for vector fields, and InvertIndexParamInput for scalar fields.

Args: params (CreateIndexInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the field to index - index_param: One of HnswIndexParamInput, FlatIndexParamInput, IVFIndexParamInput, or InvertIndexParamInput (use 'type' field as discriminator)

Returns: str: Success message or error message

Examples: - Use when: "Create an HNSW index on the embedding field" - Use when: "Build an inverted index on the category scalar field"

Inputs: params (required). Returns: result

delete_documentsB

DestructiveIdempotent

Delete documents by their IDs.

Args: params (DeleteDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - document_ids (List[str]): Document IDs to delete

Returns: str: Success message with deletion count or error message

Inputs: params (required). Returns: result

destroy_collectionA

Destructive

Permanently delete a collection from disk.

WARNING: This operation is irreversible. All data will be permanently lost.

Args: params (DestroyCollectionInput): Validated input parameters containing: - collection_name (str): Collection identifier

Returns: str: Success confirmation or error message

Inputs: params (required). Returns: result

drop_indexB

DestructiveIdempotent

Remove the index from a field.

Args: params (DropIndexInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the indexed field

Returns: str: Success message or error message

Inputs: params (required). Returns: result

embedding_searchA

Read-onlyIdempotent

Convert a natural language query to a vector and perform similarity search.

Embeds query_text using OpenAIDenseEmbedding, then runs a vector similarity search against the specified field in the collection. This is the high-level search interface: supply a natural language query, get ranked results.

OpenAI connection is read from environment variables: OPENAI_API_KEY, OPENAI_BASE_URL (optional), OPENAI_EMBEDDING_MODEL (optional). The embedding dimension is inferred from the collection schema automatically.

Args: params (EmbeddingSearchInput): - collection_name: Target collection - field_name: Vector field to search - query_text: Natural language query to embed and search with - topk: Number of results (default: 10) - filter: Optional scalar filter expression - response_format: Output format ('markdown' or 'json')

Returns: str: Search results sorted by similarity, or error

Inputs: params (required). Returns: result

embedding_writeA

Embed text documents and upsert them into a Zvec collection.

Converts each document's text field to a dense vector using OpenAIDenseEmbedding, then upserts all documents into the specified collection. This is the high-level write interface: supply plain text, get vectors stored automatically.

Args: params (EmbeddingWriteInput): - collection_name: Target collection - field_name: Vector field to populate - documents: List of {id, text, fields} — text is auto-embedded

Returns: str: Success message with upsert count, or error

Inputs: params (required). Returns: result

fetch_documentsB

Read-onlyIdempotent

Retrieve documents by their IDs.

Args: params (FetchDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - document_ids (List[str]): Document IDs to fetch - response_format (ResponseFormat): Output format

Returns: str: Documents in the requested format or error message

Inputs: params (required). Returns: result

generate_dense_embeddingA

Read-onlyIdempotent

Generate a dense embedding vector for a piece of text using OpenAIDenseEmbedding.

Converts text into a fixed-length dense vector via the OpenAI (or compatible) embedding API. The resulting vector can be directly used for similarity search.

Args: params (GenerateDenseEmbeddingInput): - text: Text to embed - api_key: OpenAI API key (or OPENAI_API_KEY env var) - base_url: Custom API base URL for OpenAI-compatible endpoints - model: Embedding model name (default: text-embedding-3-small) - dimension: Output vector dimension (default: 1536)

Returns: str: JSON with text preview, model, dimension, and the dense vector

Inputs: params (required). Returns: result

get_collection_infoA

Read-onlyIdempotent

Get detailed information about an opened collection.

Retrieves schema definition, statistics, and configuration of a collection.

Args: params (GetCollectionInfoInput): Validated input parameters containing: - collection_name (str): Collection identifier - response_format (ResponseFormat): Output format ('markdown' or 'json')

Returns: str: Collection information in the requested format or error message

Inputs: params (required). Returns: result

insert_documentsA

Insert new documents into a collection.

Documents must have unique IDs and conform to the collection schema. This operation fails if a document with the same ID already exists.

Args: params (InsertDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents to insert

Returns: str: Success message with insertion count or error message

Inputs: params (required). Returns: result

multi_vector_queryA

Read-onlyIdempotent

Perform multi-vector similarity search with score fusion and re-ranking.

This tool searches across multiple vector embeddings simultaneously and combines their results using a re-ranking strategy. This is useful when documents have multiple types of embeddings (e.g., dense + sparse, text + image).

Args: params (MultiVectorQueryInput): Validated input parameters containing: - collection_name (str): Collection identifier - vectors (List[MultiVectorQuerySpec]): List of vector queries (min 2) - topk (int): Candidates to retrieve from each vector field (default: 10) - topn (int): Final documents to return after re-ranking (default: 5) - reranker_type (str): 'weighted' or 'rrf' (default: weighted) - weights (Optional[Dict[str, float]]): Field weights for weighted re-ranker - rank_constant (int): RRF rank constant (default: 60) - metric_type (str): Metric for weighted re-ranker (default: IP) - filter (Optional[str]): Filter expression - response_format (str): Output format

Returns: str: Re-ranked search results or error message

Examples: - Use when: "Search using both dense and sparse embeddings" - Use when: "Combine text and image similarity for multi-modal search"

Re-ranking Strategies: - Weighted: Combines normalized scores with custom weights per field Best when scores are comparable and you know field importance - RRF (Reciprocal Rank Fusion): Combines based on rank positions only Best when scores use different metrics/scales or prefer tuning-free approach

Inputs: params (required). Returns: result

open_collectionA

Idempotent

Open an existing Zvec collection from disk.

This tool opens a previously created collection and caches it for subsequent operations. The collection must have been created with zvec_create_and_open_collection.

Args: params (OpenCollectionInput): Validated input parameters containing: - path (str): Filesystem path of the existing collection - collection_name (str): Unique session identifier for caching - read_only (bool): Open in read-only mode (default: False)

Returns: str: Success message with collection details or error message

Examples: - Use when: "Open the collection at ./my_vectors" - Use when: "Load existing vector database from ./embeddings" - Don't use when: Collection doesn't exist (use create_and_open_collection)

Inputs: params (required). Returns: result

optimize_collectionA

Idempotent

Optimize the collection (e.g., merge segments, rebuild index).

This operation improves query performance and reduces storage overhead.

Args: params (OptimizeCollectionInput): Validated input parameters containing: - collection_name (str): Collection identifier

Returns: str: Success message or error message

Inputs: params (required). Returns: result

update_documentsA

Idempotent

Update existing documents by ID.

Only specified fields are updated; others remain unchanged. Documents must already exist.

Args: params (UpdateDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents with updates

Returns: str: Success message with update count or error message

Inputs: params (required). Returns: result

upsert_documentsA

Idempotent

Insert new documents or update existing ones by ID.

This operation inserts documents if they don't exist, or updates them if they do.

Args: params (UpsertDocumentsInput): Validated input parameters containing: - collection_name (str): Collection identifier - documents (List[DocumentInput]): Documents to upsert

Returns: str: Success message with upsert count or error message

Inputs: params (required). Returns: result

vector_queryA

Read-onlyIdempotent

Perform vector similarity search with optional filtering.

This tool searches for the most similar documents based on vector similarity. Optionally apply scalar filters to restrict results to a subset of documents.

Args: params (VectorQueryInput): Validated input parameters containing: - collection_name (str): Collection identifier - field_name (str): Name of the vector field to query - vector (List[float]): Query vector - topk (int): Number of results to return (default: 10, max: 1000) - filter (Optional[str]): Filter expression (e.g., 'age > 25 AND city == "NYC"') - response_format (ResponseFormat): Output format

Returns: str: Search results sorted by similarity score or error message

Examples: - Use when: "Find the 10 most similar documents to this embedding" - Use when: "Search for similar vectors with age > 30" - Filter syntax: "field_name > value", "field == 'string'", combined with AND/OR

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-06-15 03:20 across 17 tools

Disambiguation5/5

Each tool targets a distinct operation: collection lifecycle (create/open/destroy/info/optimize), document CRUD (insert/update/upsert/delete/fetch), index management (create/drop), and search variants (vector_query, embedding_search, multi_vector_query). There is no apparent overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern (e.g., create_and_open_collection, fetch_documents, generate_dense_embedding). There is no mixing of conventions, and the naming clearly conveys the action and resource.

Tool Count5/5

17 tools cover the full vector database workflow without being excessive. Each tool serves a clear purpose, from collection management to high-level embedding search, making the surface appropriately scoped.

Completeness4/5

The tool set covers most essential operations: collection CRUD, document CRUD, indexing, multiple search modes, and embedding generation. A minor gap is the lack of a tool to list all available collections, which may require external file system access, but the core workflow is complete.

Maintenance

ActivityInactive

ResponsivenessOutdated data

Resources

Related MCP Connectors

ragie
com.mcparmory
Ingest, manage, and retrieve documents for RAG-powered AI applications
RAG Systems Databases Knowledge & Memory
2
https://mcp.mcparmory.com/ragie
Astra DB
io.github.erichare
Astra DB tools for agents: schema, find, vector search, guarded writes, and interactive views.
Databases Vector Databases
1
https://astra-widgets-mcp.vercel.app/mcp
Memwyre
io.github.memwyreai
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Knowledge & Memory RAG Systems
11
https://server.memwyre.tech/mcp/
agentbay-mcpA
io.github.thomasjumper
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Knowledge & Memory Autonomous Agents Agent Orchestration
21
https://www.aiagentsbay.com/api/mcp

Related MCP Servers

MCP VectorStore Server
Vector Databases Search File Systems
BierschneiderEmanuel
A
license
Not graded
quality
D
maintenance
Provides advanced document search and processing capabilities through vector stores, including PDF processing, semantic search, web search integration, and file operations. Enables users to create searchable document collections and retrieve relevant information using natural language queries.
Updated a year ago (2025-08-16 14:28 UTC)
MIT
Milvus MCP Server
Vector Databases RAG Systems AI & Machine Learning
hcheng666
A
license
Not graded
quality
D
maintenance
Enables large language models to interact with Milvus vector databases through natural language, supporting semantic search with built-in OpenAI-compatible embedding services and comprehensive collection management.
Updated 7 months ago (2026-04-23 01:35 UTC)
ISC
zvec-mcp
Vector Databases RAG Systems
cluster2600
A
license
Not graded
quality
D
maintenance
Enables AI agents to store, search, and manage a local vector database for RAG knowledge retrieval and long-term memory, powered by zvec.
Updated 9 months ago (2026-02-26 10:36 UTC)
1
Apache 2.0
Milvus MCP Server
Vector Databases Search
stephen37
F
license
Not graded
quality
D
maintenance
Enables LLMs to interact with Milvus vector database for search, query, and collection management operations.
Updated 2 years ago (2025-03-10 14:48 UTC)
8
-

Zvec MCP Server

Overview

Features

Installation

Requirements

Install from PyPI

Install from Source

Quick Start

Running the Server

IDE Integration (Qoder/Cursor/Claude Desktop)

Basic Usage Example

Available Tools

Collection Management (4 tools)

Document Operations (5 tools)

Vector Search (2 tools)

Index Management (3 tools)

AI Embedding (3 tools)

Tool Details

Vector Data Types

Scalar Data Types

Index Types

Distance Metrics

Re-ranking Strategies (Multi-Vector Query)

Architecture

Modular Structure

MCP Resources

Error Handling

Response Formats

Development

Running Tests

References

License

Contributing

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP VectorStore Server

Milvus MCP Server

zvec-mcp

Milvus MCP Server