Knuckles-Team/vector-mcp
If you are the rightful owner of vector-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Vector MCP Server for AI Agents - Supports ChromaDB, Couchbase, MongoDB, Qdrant, and PGVector
Vector Database MCP Server
Version: 0.1.14
This is an MCP Server implementation which allows for a standardized collection management system across vector database technologies.
This was heavily inspired by the RAG implementation of Microsoft's Autogen V1 framework, however, this was changed to an MCP server model instead.
AI Agents can:
- Create collections with documents stored on the local filesystem or URLs
- Add documents to a collection
- Utilize collection for retrieval augmented generation (RAG)
- Delete collection
Supports:
- ChromaDB
- PGVector - 90% Tested
- Couchbase - 80% Tested
- Qdrant - 80% Tested
- MongoDB - 80% Tested
This repository is actively maintained - Contributions and bug reports are welcome!
Automated tests are planned
Usage:
MCP CLI
| Short Flag | Long Flag | Description |
|---|---|---|
| -h | --help | Display help information |
| -t | --transport | Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio) |
| -s | --host | Host address for HTTP transport (default: 0.0.0.0) |
| -p | --port | Port number for HTTP transport (default: 8000) |
| --auth-type | Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none) | |
| --token-jwks-uri | JWKS URI for JWT verification | |
| --token-issuer | Issuer for JWT verification | |
| --token-audience | Audience for JWT verification | |
| --oauth-upstream-auth-endpoint | Upstream authorization endpoint for OAuth Proxy | |
| --oauth-upstream-token-endpoint | Upstream token endpoint for OAuth Proxy | |
| --oauth-upstream-client-id | Upstream client ID for OAuth Proxy | |
| --oauth-upstream-client-secret | Upstream client secret for OAuth Proxy | |
| --oauth-base-url | Base URL for OAuth Proxy | |
| --oidc-config-url | OIDC configuration URL | |
| --oidc-client-id | OIDC client ID | |
| --oidc-client-secret | OIDC client secret | |
| --oidc-base-url | Base URL for OIDC Proxy | |
| --remote-auth-servers | Comma-separated list of authorization servers for Remote OAuth | |
| --remote-base-url | Base URL for Remote OAuth | |
| --allowed-client-redirect-uris | Comma-separated list of allowed client redirect URIs | |
| --eunomia-type | Eunomia authorization type: 'none', 'embedded', 'remote' (default: none) | |
| --eunomia-policy-file | Policy file for embedded Eunomia (default: mcp_policies.json) | |
| --eunomia-remote-url | URL for remote Eunomia server |
Using as an MCP Server
The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:
Run in stdio mode (default):
vector-mcp --transport "stdio"
Run in HTTP mode:
vector-mcp --transport "http" --host "0.0.0.0" --port "8000"
Creating Collection
AI Prompt:
Create a collection called zapdos with the documents in this directory:
/home/user/Documents/Chroma
AI Response:
The collection named "zapdos" has been successfully created or retrieved from the vector database
using the documents in the directory /home/user/Documents/Chroma.
Let me know if you'd like to perform any further actions, such as querying the collection or adding more documents!
Retrieving from Collection
AI Prompt:
Create a collection called zapdos with the documents in this directory:
/home/user/Documents/Chroma
AI Response:
The collection named "zapdos" has been successfully created or retrieved from the vector database
using the documents in the directory /home/user/Documents/Chroma.
Let me know if you'd like to perform any further actions, such as querying the collection or adding more documents!
Deleting Collection
AI Prompt:
Delete the collection called memory
AI Response:
The collection named "memory" has been successfully deleted.
Let me know if you'd like to create a new collection or perform any other actions!
Deploy MCP Server as a Service
The MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.
Using Docker Run
docker pull knucklessg1/vector-mcp:latest
docker run -d \
--name vector-mcp \
-p 8004:8004 \
-e HOST=0.0.0.0 \
-e PORT=8004 \
-e TRANSPORT=http \
-e AUTH_TYPE=none \
-e EUNOMIA_TYPE=none \
knucklessg1/vector-mcp:latest
For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:
docker run -d \
--name vector-mcp \
-p 8004:8004 \
-e HOST=0.0.0.0 \
-e PORT=8004 \
-e TRANSPORT=http \
-e AUTH_TYPE=oidc-proxy \
-e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
-e OIDC_CLIENT_ID=your-client-id \
-e OIDC_CLIENT_SECRET=your-client-secret \
-e OIDC_BASE_URL=https://your-server.com \
-e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
-e EUNOMIA_TYPE=embedded \
-e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
knucklessg1/vector-mcp:latest
Using Docker Compose
Create a docker-compose.yml file:
services:
vector-mcp:
image: knucklessg1/vector-mcp:latest
environment:
- HOST=0.0.0.0
- PORT=8004
- TRANSPORT=http
- AUTH_TYPE=none
- EUNOMIA_TYPE=none
ports:
- 8004:8004
For advanced setups with authentication and Eunomia:
services:
vector-mcp:
image: knucklessg1/vector-mcp:latest
environment:
- HOST=0.0.0.0
- PORT=8004
- TRANSPORT=http
- AUTH_TYPE=oidc-proxy
- OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
- OIDC_CLIENT_ID=your-client-id
- OIDC_CLIENT_SECRET=your-client-secret
- OIDC_BASE_URL=https://your-server.com
- ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
- EUNOMIA_TYPE=embedded
- EUNOMIA_POLICY_FILE=/app/mcp_policies.json
ports:
- 8004:8004
volumes:
- ./mcp_policies.json:/app/mcp_policies.json
Run the service:
docker-compose up -d
Configure mcp.json for AI Integration
{
"mcpServers": {
"vector_mcp": {
"command": "uv",
"args": [
"run",
"--with",
"vector-mcp",
"vector-mcp"
],
"env": {
"DATABASE_TYPE": "chromadb", // Optional
"COLLECTION_NAME": "memory", // Optional
"DOCUMENT_DIRECTORY": "/home/user/Documents/" // Optional
},
"timeout": 300000
}
}
}
Installation Instructions:
Install Python Package
python -m pip install vector-mcp
PGVector dependencies
python -m pip install vector-mcp[pgvector]
All
python -m pip install vector-mcp[all]
or
uv pip install --upgrade vector-mcp[all]
Repository Owners:
Special shoutouts to Microsoft Autogen V1 ♥️