Zvec MCP: vector database for agents
Zvec MCP Server
17 MCP tools let an agent create Zvec collections, write documents and search by meaning with HNSW, IVF and FLAT indexes
- 13 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The agent writes and deletes documents in a local database, and destroy_collection erases a collection permanently
- Texts for embeddings go to the external OpenAI API together with your key
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/zvec-mcp-serverDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent writes and deletes documents in a local database, and destroy_collection erases a collection permanently
- Texts for embeddings go to the external OpenAI API together with your key
This is third-party code. Review the repository files before installing.
What it does
Zvec is an embedded vector database from Alibaba, and this MCP server opens it to an agent through 17 Python tools. The agent creates and opens collections with a schema of vector and scalar fields, inserts, updates, deletes and reads documents, builds HNSW, IVF and FLAT indexes and optimizes a collection. Search comes in two kinds. A single-vector query accepts a filter on scalar fields. A multi-vector query combines several embeddings and ranks results by weights or by RRF. Distance metrics are cosine, inner product and L2. Three tools work with text: generate_dense_embedding builds a vector through the OpenAI API, embedding_write turns text into vectors and writes them to a collection at once, and embedding_search searches by a natural-language query. Output comes as JSON or Markdown, and two resources, zvec://collections and zvec://collection/{collection_name}, show opened collections.
Who it is for. Developers of semantic-search and RAG pipelines who store vectors locally in Zvec and want to manage the database in chat.
Good fit when
- A RAG prototype needs a local collection, and its field schema is described to the agent in words
- A batch of notes has to become embeddings and be written to a collection at once
- Semantic search is combined with a filter on scalar fields such as author or date
- Results from several embeddings are merged through weighted fusion or RRF
- An HNSW index is rebuilt when the collection has grown, and the collection is optimized
Not a fit when
- Vectors live on a server such as Qdrant, Chroma or Milvus: this server works only with the embedded Zvec database
- Embeddings must not go to OpenAI: every tool with embedding in its name calls its API
- You only need to search project files: the zvec-grep utility is simpler for that
Example request
Create a docs_col collection in ./my_vectors with a 1536-dimension embedding field, add three notes with auto-embedding and find the closest one to the query "neural networks".MCP
- Transport
- stdio
- Authentication
- API key
Environment variables
OPENAI_API_KEYrequired, secret- OpenAI key for the embedding tools
OPENAI_BASE_URL- Alternative API endpoint such as DashScope
OPENAI_EMBEDDING_MODEL- Embedding model, text-embedding-3-small by default
Limitations
You need Python 3.10–3.14 and Linux (x86_64, ARM64), macOS (ARM64) or Windows (x86_64). The embedding tools require OPENAI_API_KEY, and OPENAI_BASE_URL lets you substitute a compatible endpoint such as DashScope.
The destroy_collection tool deletes a collection permanently. The last commit in the repository was made in April 2026. Without a key only the 14 tools that take ready vectors work.
How to disable. Remove the zvec-mcp entry from the client config and restart it. Uninstall the package with pip uninstall zvec-mcp-server, and delete collection directories on disk by hand if you no longer need them.
FAQ
How do I connect Zvec MCP to Claude Desktop?
Add a zvec-mcp entry to claude_desktop_config.json with the command uvx, the argument zvec-mcp-server and OPENAI_API_KEY in the env block, then restart the app. You can test the server without a client through npx @modelcontextprotocol/inspector python -m zvec_mcp.
Do I need an OpenAI key?
Only for the three embedding tools: generate_dense_embedding, embedding_write and embedding_search. The other 14 work with ready vectors. The default model is text-embedding-3-small, changed by OPENAI_EMBEDDING_MODEL.
Which indexes and metrics are available?
Vector indexes HNSW, IVF and FLAT, and the scalar INVERT. Metrics: COSINE, IP and L2. Multi-vector search offers weighted fusion and RRF.
Does the server work with Cursor?
Yes, Cursor is listed among the clients, and the config is the same as for Claude Desktop. The settings file depends on the client, for example mcp.json.
Which systems does the server run on?
It needs Python 3.10–3.14 on Linux (x86_64 and ARM64), macOS (ARM64) or Windows (x86_64). No other combinations are declared.
Discussion
No questions or reviews yet.
Related
MCP serversThe Zvec skill guides an agent through the embedded vector database: collection schema, hybrid search, RAG and multimodal queries
Official Zilliz MCP server: the agent runs vector and text search and manages collections and data in Milvus
The official MCP server for the Chroma vector database: collections, documents, semantic and full-text search
Official Pinecone MCP server: documentation search, index creation, record upserts and search from your agent
A local MCP server that turns a folder of documents into a knowledge base with hybrid search for Claude Code and Cursor
A self-hosted RAG app with a web interface and a built-in MCP server: documents, Qdrant and answers with sources.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Zvec MCP: vector database for agents (this card) | yes | API key | 13 | |
| zvec-grep | no | not required | 4,229 | a ripgrep, BM25 and vector search utility for files, while this manages Zvec collections |
| Qdrant MCP Server | yes | key is optional | 1,563 | a server for the Qdrant vector database, while this uses the embedded Zvec database with no separate server |
| Chroma MCP Server | yes | not required | 601 | a server for the Chroma vector database, while this adds Zvec HNSW, IVF, FLAT indexes and multi-vector search |
README in short
The package installs from PyPI or from source and starts with python -m zvec_mcp. Config examples for Qoder and Claude Desktop, a three-call example (create a collection, write with embedding, search) and the tools by group are provided. Pydantic v2 validates inputs. The license is Apache 2.0.