https://github.com/knuckles-team/vector-mcp
Vector MCP Server for AI Agents - Supports ChromaDB, Couchbase, MongoDB, Qdrant, and PGVector
https://github.com/knuckles-team/vector-mcp
a2a a2a-server ag-ui chromadb couchbase mcp-server mongodb mongodb-atlas pgvector python qdrant qdrant-vector-database rag retrieval-augmented-generation
Last synced: 1 day ago
JSON representation
Vector MCP Server for AI Agents - Supports ChromaDB, Couchbase, MongoDB, Qdrant, and PGVector
- Host: GitHub
- URL: https://github.com/knuckles-team/vector-mcp
- Owner: Knuckles-Team
- License: mit
- Created: 2025-08-30T14:20:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-02-08T06:41:31.000Z (4 days ago)
- Last Synced: 2026-02-08T06:48:05.000Z (4 days ago)
- Topics: a2a, a2a-server, ag-ui, chromadb, couchbase, mcp-server, mongodb, mongodb-atlas, pgvector, python, qdrant, qdrant-vector-database, rag, retrieval-augmented-generation
- Language: Python
- Homepage:
- Size: 604 KB
- Stars: 8
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vector Database - A2A | AG-UI | MCP
*Version: 1.1.2*
## Overview
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:
- Hybrid search for document information (lexical/vector)
- 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
- Couchbase
- Qdrant
- MongoDB
This repository is actively maintained - Contributions and bug reports are welcome!
Automated tests are planned
## MCP
### MCP Tools
| Function Name | Description | Tag(s) |
|:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------|:------------------------|
| `create_collection` | Creates a new collection or retrieves an existing one in the vector database. | `collection_management` |
| `semantic_search` | Retrieves and gathers related knowledge from the vector database instance using the question variable. | `semantic_search` |
| `add_documents` | Adds documents to an existing collection in the vector database. This can be used to extend collections with additional documents. | `collection_management` |
| `delete_collection` | Deletes a collection from the vector database. | `collection_management` |
| `list_collections` | Lists all collections in the vector database. | `collection_management` |
## A2A Agent
### Architecture:
```mermaid
---
config:
layout: dagre
---
flowchart TB
subgraph subGraph0["Agent Capabilities"]
C["Agent"]
B["A2A Server - Uvicorn/FastAPI"]
D["MCP Tools"]
F["Agent Skills"]
end
C --> D & F
A["User Query"] --> B
B --> C
D --> E["Platform API"]
C:::agent
B:::server
A:::server
classDef server fill:#f9f,stroke:#333
classDef agent fill:#bbf,stroke:#333,stroke-width:2px
style B stroke:#000000,fill:#FFD600
style D stroke:#000000,fill:#BBDEFB
style F fill:#BBDEFB
style A fill:#C8E6C9
style subGraph0 fill:#FFF9C4
```
### Component Interaction Diagram
```mermaid
sequenceDiagram
participant User
participant Server as A2A Server
participant Agent as Agent
participant Skill as Agent Skills
participant MCP as MCP Tools
User->>Server: Send Query
Server->>Agent: Invoke Agent
Agent->>Skill: Analyze Skills Available
Skill->>Agent: Provide Guidance on Next Steps
Agent->>MCP: Invoke Tool
MCP-->>Agent: Tool Response Returned
Agent-->>Agent: Return Results Summarized
Agent-->>Server: Final Response
Server-->>User: Output
```
## 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):
```bash
vector-mcp --transport "stdio"
```
#### Run in HTTP mode:
```bash
vector-mcp --transport "http" --host "0.0.0.0" --port "8000"
```
### Creating Collection
AI Prompt:
```text
Create a collection called zapdos with the documents in this directory:
/home/user/Documents/Chroma
```
AI Response:
```text
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:
```text
Create a collection called zapdos with the documents in this directory:
/home/user/Documents/Chroma
```
AI Response:
```text
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:
```text
Delete the collection called memory
```
AI Response:
```text
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!
```
### A2A CLI
#### Endpoints
- **Web UI**: `http://localhost:8000/` (if enabled)
- **A2A**: `http://localhost:8000/a2a` (Discovery: `/a2a/.well-known/agent.json`)
- **AG-UI**: `http://localhost:8000/ag-ui` (POST)
| Short Flag | Long Flag | Description |
|------------|-------------------|------------------------------------------------------------------------|
| -h | --help | Display help information |
| | --host | Host to bind the server to (default: 0.0.0.0) |
| | --port | Port to bind the server to (default: 9000) |
| | --reload | Enable auto-reload |
| | --provider | LLM Provider: 'openai', 'anthropic', 'google', 'huggingface' |
| | --model-id | LLM Model ID (default: qwen3:4b) |
| | --base-url | LLM Base URL (for OpenAI compatible providers) |
| | --api-key | LLM API Key |
| | --mcp-url | MCP Server URL (default: http://localhost:8000/mcp) |
| | --web | Enable Pydantic AI Web UI | False (Env: ENABLE_WEB_UI) |
### Deploy MCP Server as a Service
The MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.
#### Using Docker Run
```bash
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:
```bash
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:
```yaml
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:
```yaml
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:
```bash
docker-compose up -d
```
#### Configure `mcp.json` for AI Integration
```json
{
"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
}
}
}
```
## Install Python Package
```bash
python -m pip install vector-mcp
```
PGVector dependencies
```bash
python -m pip install vector-mcp[postgres]
```
All
```bash
python -m pip install vector-mcp[all]
```
or
```bash
uv pip install --upgrade vector-mcp[all]
```
## Repository Owners
Special shoutouts to Microsoft Autogen V1 ♥️