Metadata-Version: 2.4
Name: mad-mcp-qdrant
Version: 1.1.14
Summary: MCP server for retrieving context from a Qdrant vector database
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastembed>=0.6.0
Requires-Dist: fastmcp==2.7.0
Requires-Dist: openai>=1.40.0
Requires-Dist: pdf2image>=1.17.0
Requires-Dist: pydantic<2.12.0,>=2.10.6
Requires-Dist: pypdf>=4.2.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: python-docx>=1.1.0
Requires-Dist: qdrant-client>=1.12.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/brand/header.jpg" alt="MADPANDA3D QDRANT MCP header" />
</p>

<p align="center">
  <a href="https://github.com/MADPANDA3D/QDRANT-MCP/actions/workflows/pre-commit.yaml">
    <img src="https://img.shields.io/github/actions/workflow/status/MADPANDA3D/QDRANT-MCP/pre-commit.yaml?branch=main" alt="pre-commit status" />
  </a>
  <a href="https://github.com/MADPANDA3D/QDRANT-MCP/actions/workflows/pytest.yaml">
    <img src="https://img.shields.io/github/actions/workflow/status/MADPANDA3D/QDRANT-MCP/pytest.yaml?branch=main" alt="tests status" />
  </a>
  <a href="https://github.com/MADPANDA3D/QDRANT-MCP/releases">
    <img src="https://img.shields.io/github/v/release/MADPANDA3D/QDRANT-MCP?display_name=tag" alt="release" />
  </a>
  <a href="https://github.com/MADPANDA3D/QDRANT-MCP/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/MADPANDA3D/QDRANT-MCP" alt="license" />
  </a>
</p>

<h1 align="center"><strong>MADPANDA3D QDRANT MCP</strong></h1>
<p align="center">
  <strong>Manage your Vector Database how you see fit</strong>
</p>
<p align="center">
  MADPANDA3D QDRANT MCP is a production-ready Model Context Protocol server for Qdrant.
  It turns your vector store into a managed memory layer with structured controls for
  ingest, retrieval, validation, and ongoing cleanup.
</p>
<p align="center">
  Use it to keep memories clean, deduped, and relevance-tuned over time. The toolkit
  includes safe dry-run previews, bulk maintenance jobs with progress reporting, and
  operational guardrails so agents can manage your database at scale without chaos.
</p>

## Deploy

- [![Deploy on Railway](https://railway.app/button.svg)](https://example.com/railway-deploy)
- [![Deploy with Vercel](https://vercel.com/button)](https://example.com/vercel-deploy)
- [![Deploy to VPS](https://img.shields.io/badge/Deploy_to_VPS-Hostinger-blue?style=for-the-badge&logo=linux&logoColor=white)](https://example.com/vps-deploy)
- [![Donate to the Project](https://img.shields.io/badge/Donate_to_the_Project-Support_Development-ff69b4?style=for-the-badge&logo=heart&logoColor=white)](https://example.com/donate)

<details>
<summary>DEPLOY ON VPS</summary>

- [![Hostinger VPS KVM 1](https://img.shields.io/badge/Hostinger_VPS_KVM_1-Deploy-blue?style=for-the-badge&logo=linux&logoColor=white)](https://www.hostinger.com/cart?product=vps%3Avps_kvm_1&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a491-d783-7057-85d2-27de6e01e2c5)
- [![Hostinger VPS KVM 2](https://img.shields.io/badge/Hostinger_VPS_KVM_2-Deploy-blue?style=for-the-badge&logo=linux&logoColor=white)](https://www.hostinger.com/cart?product=vps%3Avps_kvm_2&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a492-26cf-7333-b6d7-692e17bf8ce1)
- [![Hostinger VPS KVM 4](https://img.shields.io/badge/Hostinger_VPS_KVM_4-Deploy-blue?style=for-the-badge&logo=linux&logoColor=white)](https://www.hostinger.com/cart?product=vps%3Avps_kvm_4&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a492-531e-70d3-83f5-e28eb919466d)
- [![Hostinger VPS KVM 8](https://img.shields.io/badge/Hostinger_VPS_KVM_8-Deploy-blue?style=for-the-badge&logo=linux&logoColor=white)](https://www.hostinger.com/cart?product=vps%3Avps_kvm_8&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a492-7ce9-70fb-b96c-2184abc56764)

</details>

<details>
<summary>Hostinger Partner Links</summary>

### Cloud Hosting
- [Cloud Economy](https://www.hostinger.com/cart?product=hosting%3Acloud_economy&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a48f-e7fa-7358-9ff0-f9ba2e8d6e36)
- [Cloud Professional](https://www.hostinger.com/cart?product=hosting%3Acloud_professional&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a490-20fd-70bc-959e-a1f2cd9a69a6)
- [Cloud Enterprise](https://www.hostinger.com/cart?product=hosting%3Acloud_enterprise&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a490-5972-72e4-850f-40d618988dc1)

### Web Hosting
- [Premium](https://www.hostinger.com/cart?product=hosting%3Ahostinger_premium&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a48f-4c21-7199-9918-8f31a3f6a0d9)
- [Business](https://www.hostinger.com/cart?product=hosting%3Ahostinger_business&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a48f-1135-72ba-acbb-13e0e7550db0)

### Website Builder
- [Premium](https://www.hostinger.com/cart?product=hosting%3Ahostinger_premium&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a492-f240-7309-b3fe-9f6909fbc769&product_type=website-builder)
- [Business](https://www.hostinger.com/cart?product=hosting%3Ahostinger_business&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a492-b8f6-7147-bdc4-7c3c69256ae9&product_type=website-builder)

### Agency Hosting
- [Startup](https://www.hostinger.com/cart?product=hosting%3Aagency_startup&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a490-d03c-71de-9acf-08fd4fa911de)
- [Growth](https://www.hostinger.com/cart?product=hosting%3Aagency_growth&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a491-6af4-731f-8947-f1458f07fa5b)
- [Professional](https://www.hostinger.com/cart?product=hosting%3Aagency_professional&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a491-03fb-73f8-9910-044a0a33393a)

### Email
- [Business Pro](https://www.hostinger.com/cart?product=hostinger_mail%3Apro&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a493-5c27-727b-b7f9-8747ffb4e5ee)
- [Business Premium](https://www.hostinger.com/cart?product=hostinger_mail%3Apremium&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a493-a3fc-72b8-a961-94ed6e1c70e6)

### Reach
- [Reach 500](https://www.hostinger.com/cart?product=reach%3A500&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a494-3ebf-7367-b409-9948de50a297)
- [Reach 1000](https://www.hostinger.com/cart?product=reach%3A1000&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a494-8bb9-726e-bb8d-9de9a72a3c21)
- [Reach 2500](https://www.hostinger.com/cart?product=reach%3A2500&period=12&referral_type=cart_link&REFERRALCODE=ZUWMADPANOFE&referral_id=0199a494-c9c1-7191-b600-cafa2e9adafc)

</details>

## Quickstart

<details>
<summary>Install (pip)</summary>

```bash
pip install mad-mcp-qdrant
```

</details>

<details>
<summary>Run with Docker</summary>

```bash
docker build -t mcp-server-qdrant .
docker run -d --name mcp-qdrant \
  --env-file .env \
  mcp-server-qdrant mcp-server-qdrant --transport streamable-http
```

</details>

<details>
<summary>Run locally (uvx)</summary>

```bash
QDRANT_URL=... COLLECTION_NAME=... uvx mad-mcp-qdrant
```

Prefer `mad-mcp-qdrant`; `mcp-server-qdrant` remains as a compatible alias.

</details>

## Tools

Most mutating tools support `dry_run` + `confirm` and return a `dry_run_diff` preview for safer approvals.

<details>
<summary>Core Memory Tools</summary>

- `qdrant-store`: store a single memory point with metadata.
- `qdrant-ingest-with-validation`: validate inputs, optionally quarantine, then store.
- `qdrant-ingest-document`: chunk a document and store as multiple points.
- `qdrant-find`: query vectors with filters and return matches.
- `qdrant-update-point`: update payload fields for a point id.
- `qdrant-patch-payload`: patch specific payload keys for a point id.
- `qdrant-list-points`: scroll point ids in a collection with filters.
- `qdrant-get-points`: fetch points by id list with payload/vectors.
- `qdrant-count-points`: count points that match optional filters.

</details>

<details>
<summary>Housekeeping + Quality</summary>

- `qdrant-audit-memories`: scan for missing fields, bad payloads, and duplicates.
- `qdrant-backfill-memory-contract`: populate missing metadata fields at scale.
- `qdrant-bulk-patch`: patch payloads in bulk by filter or ids (dry-run supported).
- `qdrant-dedupe-memories`: dedupe exact matches by hash.
- `qdrant-find-near-duplicates`: cluster semantic near-duplicates.
- `qdrant-merge-duplicates`: merge duplicate groups into a canonical point.
- `qdrant-reembed-points`: recompute embeddings for selected points.
- `qdrant-expire-memories`: delete/archive memories past `expires_at_ts`.
- `qdrant-delete-points`: delete points by id list.
- `qdrant-delete-by-filter`: delete points that match a filter.
- `qdrant-delete-document`: delete all chunks for a document id.

</details>

<details>
<summary>Jobs + Progress</summary>

- `qdrant-submit-job`: start a background maintenance job.
- `qdrant-job-status`: get job status and summary.
- `qdrant-job-progress`: read progress counters and phase.
- `qdrant-job-logs`: tail recent logs for a job.
- `qdrant-job-result`: fetch the final job result.
- `qdrant-cancel-job`: cancel a running job.

</details>

<details>
<summary>Collection + Admin</summary>

- `qdrant-health-check`: validate collection health and expected indexes.
- `qdrant-metrics-snapshot`: capture collection metrics and index coverage.
- `qdrant-ensure-payload-indexes`: create missing payload indexes.
- `qdrant-optimizer-status`: report optimizer and segment status.
- `qdrant-update-optimizer-config`: update optimizer settings (admin).
- `qdrant-list-collections`: list all collections.
- `qdrant-collection-exists`: check if a collection exists.
- `qdrant-collection-info`: fetch collection config and metadata.
- `qdrant-collection-stats`: read collection stats (points, segments).
- `qdrant-collection-vectors`: show vector config for the collection.
- `qdrant-collection-payload-schema`: list payload schema + indexed fields.
- `qdrant-get-vector-name`: resolve the active vector name.
- `qdrant-list-aliases`: list all aliases.
- `qdrant-collection-aliases`: list aliases for a collection.
- `qdrant-collection-cluster-info`: cluster and shard info.
- `qdrant-list-snapshots`: list collection snapshots.
- `qdrant-list-full-snapshots`: list full snapshots on the server.
- `qdrant-list-shard-snapshots`: list shard snapshots for a collection.
- `qdrant-create-snapshot`: create a new collection snapshot.
- `qdrant-restore-snapshot`: restore a snapshot into a collection.

</details>

## Configuration

<details>
<summary>Environment Variables</summary>

| Name                       | Description                                                         | Default Value                                                     |
|----------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| `QDRANT_URL`               | URL of the Qdrant server                                            | None                                                              |
| `QDRANT_API_KEY`           | API key for the Qdrant server                                       | None                                                              |
| `COLLECTION_NAME`          | Name of the default collection to use.                              | None                                                              |
| `QDRANT_VECTOR_NAME`       | Override vector name used by the MCP server                         | None                                                              |
| `QDRANT_LOCAL_PATH`        | Path to the local Qdrant database (alternative to `QDRANT_URL`)     | None                                                              |
| `EMBEDDING_PROVIDER`       | Embedding provider to use (`fastembed` or `openai`)                  | `fastembed`                                                       |
| `EMBEDDING_MODEL`          | Name of the embedding model to use                                  | `sentence-transformers/all-MiniLM-L6-v2`                          |
| `EMBEDDING_VECTOR_SIZE`    | Vector size override (required for unknown OpenAI models)           | unset                                                             |
| `EMBEDDING_VERSION`        | Embedding version label stored with each memory                     | unset                                                             |
| `OPENAI_API_KEY`           | OpenAI API key (required for `openai` provider)                     | unset                                                             |
| `OPENAI_BASE_URL`          | OpenAI-compatible base URL (optional)                               | unset                                                             |
| `OPENAI_ORG`               | OpenAI organization ID (optional)                                   | unset                                                             |
| `OPENAI_PROJECT`           | OpenAI project ID (optional)                                        | unset                                                             |
| `TOOL_STORE_DESCRIPTION`   | Custom description for the store tool                               | See default in `src/mcp_server_qdrant/settings.py`               |
| `TOOL_FIND_DESCRIPTION`    | Custom description for the find tool                                | See default in `src/mcp_server_qdrant/settings.py`               |
| `MCP_ADMIN_TOOLS_ENABLED`  | Enable admin-only tools (optimizer updates)                         | `false`                                                           |
| `MCP_MUTATIONS_REQUIRE_ADMIN` | Require admin access for mutating tools                         | `false`                                                           |
| `MCP_MAX_BATCH_SIZE`       | Max batch size for bulk operations                                  | `500`                                                             |
| `MCP_MAX_POINT_IDS`        | Max point id list size                                              | `500`                                                             |
| `MCP_STRICT_PARAMS`        | Reject unknown keys/filters and oversized text                      | `false`                                                           |
| `MCP_MAX_TEXT_LENGTH`      | Max text length before chunking                                     | `8000`                                                            |
| `MCP_DEDUPE_ACTION`        | Dedupe behavior (`update` or `skip`)                                | `update`                                                          |
| `MCP_INGEST_VALIDATION_MODE` | Validation mode (`allow`, `reject`, `quarantine`)                 | `allow`                                                           |
| `MCP_QUARANTINE_COLLECTION` | Collection name for quarantined memories                           | `jarvis-quarantine`                                               |
| `MCP_HEALTH_CHECK_COLLECTION` | Default collection for health check                              | unset                                                             |
| `MCP_SERVER_VERSION`       | Optional git SHA for telemetry                                      | unset                                                             |

Note: You cannot provide both `QDRANT_URL` and `QDRANT_LOCAL_PATH` at the same time.

</details>

<details>
<summary>Memory Contract</summary>

Stored memories are normalized to include at least:
`text`, `type`, `entities`, `source`, `created_at`, `updated_at`, `scope`, `confidence`, and `text_hash`.

Optional fields include `expires_at` / `ttl_days`, `labels`, validation metadata
(`validation_status`, `validation_errors`), merge markers (`merged_into`, `merged_from`),
plus embedding metadata
(`embedding_model`, `embedding_dim`, `embedding_provider`, `embedding_version`).

Document ingestion stores additional fields such as `doc_id`, `doc_title`, `doc_hash`,
`source_url`, `file_name`, `file_type`, `page_start`, `page_end`, and `section_heading`.

When a duplicate `text_hash` is found in the same `scope`, the server updates
`last_seen_at` and `reinforcement_count` instead of inserting a duplicate.

</details>

<details>
<summary>Maintenance Playbooks</summary>

See `MAINTENANCE_PLAYBOOKS.md` for recommended maintenance flows.

</details>

## Release & Versioning

This repo uses conventional commits and semantic-release. Every push to `main` runs the
release workflow, and a release is created only when commit messages warrant a version bump.

## License

MIT

<p align="center">
  <img src="assets/brand/logo.jpeg" alt="MADPANDA3D logo" width="140" />
</p>
<p align="center">
  <strong>MADPANDA3D</strong>
</p>
