mad-mcp-qdrant 1.1.18

MCP server for retrieving context from a Qdrant vector database

MADPANDA3D QDRANT MCP

Manage your Vector Database how you see fit

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.

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.

Deploy

• 
• 
• 
• 

DEPLOY ON VPS

• 
• 
• 
• 

Hostinger Partner Links

Cloud Hosting

• Cloud Economy
• Cloud Professional
• Cloud Enterprise

Web Hosting

• Premium
• Business

Website Builder

• Premium
• Business

Agency Hosting

• Startup
• Growth
• Professional

Email

• Business Pro
• Business Premium

Reach

• Reach 500
• Reach 1000
• Reach 2500

Quickstart

Install (pip)

pip install mad-mcp-qdrant

Run with Docker

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

Run locally (uvx)

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

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

Tools

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

Core Memory Tools

• 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.

Housekeeping + Quality

• 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.

Jobs + Progress

• 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.

Collection + Admin

• 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.

Configuration

Environment Variables

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.

Memory Contract

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.

Maintenance Playbooks

See MAINTENANCE_PLAYBOOKS.md for recommended maintenance flows.

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

MADPANDA3D