Skip to main content
Glama
jtsang4

better-qdrant-mcp

by jtsang4

better-qdrant-mcp

An MCP server implemented with fastmcp, OpenAI embeddings, and qdrant-client, providing long-term memory and semantic search on top of Qdrant.

User Guide

Features

  • MCP server built with fastmcp

  • Hybrid search in Qdrant (dense OpenAI embeddings + sparse BM25)

  • Chinese support via jieba

  • Knowledge Base tools (renamed from memory tools to avoid conflict):

    • store-knowledge

    • store-knowledge-bulk

    • search-knowledge

    • get-knowledge-by-id

    • inspect-knowledge-base

    • delete-knowledge

  • Multiple transports: stdio, SSE, streamable HTTP

Requirements

  • Python 3.12+

  • Qdrant reachable via HTTP

Quick Start (published package)

The project is published as the better-qdrant-mcp package, so you can run it directly with uvx without cloning this repo.

1. Environment variables (required for all transports)

Minimal env for typical use:

  • QDRANT_URL – defaults to http://localhost:6333

  • QDRANT_API_KEY – optional

  • COLLECTION_NAME – optional default collection

  • OPENAI_API_KEY (or OPENAPI_API_KEY) – required

  • OPENAI_BASE_URL – optional

  • OPENAI_EMBEDDING_MODEL – defaults to text-embedding-3-small

Advanced / transport-related env:

  • MCP_TRANSPORTstdio | sse | streamable-http (default: stdio)

  • MCP_HOST – host for HTTP-based transports (default: 0.0.0.0)

  • MCP_PORT – port for HTTP-based transports (default: 8000)

  • MCP_PATH – path for HTTP transports (default: /mcp)

2. Available MCP tools

Once the server is running, the MCP client will see these tools:

  • store-knowledge(content: str, title?: str, tags?: list[str], metadata?: dict, collection_name?: str) -> str

  • store-knowledge-bulk(items: list[KnowledgeItem], collection_name?: str) -> str

  • search-knowledge(query: str, limit?: int=5, collection_name?: str) -> str

  • get-knowledge-by-id(ids: list[str] | str, collection_name?: str) -> str

  • inspect-knowledge-base(collection_name?: str) -> str

  • delete-knowledge(ids: list[str] | str, collection_name?: str) -> str

store-knowledge automatically embeds the text using OpenAI and stores it in Qdrant (Knowledge Base), returning the stored point ID. The title and tags fields help improve search context and categorization.

store-knowledge-bulk efficiently stores multiple knowledge items at once using batch embedding. Each item in the list should include content (required), and optionally title, tags, and metadata fields. This is more efficient than calling store-knowledge multiple times.

search-knowledge uses hybrid search in Qdrant (dense + sparse). If the collection is configured with named vectors dense and sparse, queries are ranked by fusing dense OpenAI embeddings and sparse BM25 scores; otherwise it falls back to dense-only search.

get-knowledge-by-id retrieves the complete payload information for one or more knowledge items by their point IDs. Use this to inspect the full details of stored items (including content, title, tags, metadata, and stored_at timestamp). You can pass a single ID or a list of IDs (typically using the id field returned by search-knowledge).

inspect-knowledge-base shows the collection configuration and sample data points, useful for debugging and verification.

delete-knowledge deletes one or more stored knowledge items from Qdrant by their point IDs. You can pass a single ID or a list of IDs (typically using the id field returned by search-knowledge).

3. Start the server

You can either specify the transport via CLI flags (recommended for quick start) or via env (MCP_TRANSPORT).

Standard IO (stdio) – default
uvx better-qdrant-mcp

In this mode, you configure your MCP client to use stdio transport and just invoke the binary; no HTTP URL is needed.

Server-Sent Events (SSE)
# Default host 0.0.0.0 and port 8000
uvx better-qdrant-mcp --transport sse

# Custom host and port
uvx better-qdrant-mcp --transport sse --host 0.0.0.0 --port 3000

Connection details for MCP clients:

  • Transport: sse

  • URL: http://<host>:<port>/sse (for example: http://localhost:8000/sse)

# Default host 0.0.0.0, port 8000 and path /mcp
uvx better-qdrant-mcp --transport streamable-http

# Custom host, port, and path
uvx better-qdrant-mcp --transport streamable-http --host 0.0.0.0 --port 3000 --path /api/mcp

Connection details for MCP clients:

  • Transport: streamable-http

  • URL: http://<host>:<port><path> (for example: http://localhost:8000/mcp)

Related MCP server: local-memory-mcp

Development Guide

Local installation (for development)

If you want to work on this repo locally instead of using the published package:

# using uv (recommended)
uv sync

# or with pip (editable install)
pip install -e .

Local build

For local development, you can use the provided Makefile:

make build

This command will first clean the dist directory and then run uv build to produce fresh artifacts.

Docker Deployment

Docker Compose provides Qdrant + this MCP server as a single service. Transport (stdio, sse, streamable-http) is selected via MCP_TRANSPORT.

The Docker image is built and published automatically to GitHub Container Registry as:

  • ghcr.io/jtsang4/better-qdrant-mcp:latest

  • Additional tags for branches, tags, and commit SHAs

The provided docker-compose.yml uses this published image directly, so you do not need to build the image locally.

# Start Qdrant + MCP using the published image
docker compose up -d

# Pull the latest published image and restart services
docker compose pull mcp && docker compose up -d

# Stop services
docker compose down

License

MIT

Available Tools

6 tools
delete-knowledgeA

Delete specific information from the knowledge base using point IDs. Use the 'id' field returned from search-knowledge results.

ParametersJSON Schema
NameRequiredDescriptionDefault
idsYesA single point ID or a list of point IDs to delete. Use the 'id' from search-knowledge results.
collection_nameNoOptional collection to target; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of disclosing destructive behavior. It only says 'Delete' and does not warn that deletion is permanent/irreversible, nor does it mention permissions or side effects. This is similar to update_drive which scored 2.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with the action front-loaded. Every word serves a purpose: it defines the action, resource, and input source.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of a detailed schema and output schema, the description provides sufficient context for a delete tool. It explains where to get IDs and what the tool does. It could mention bulk deletion or irreversibility, but these are not essential for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents both parameters with 100% coverage, including 'Use the id from search-knowledge results.' The description adds no new information about the parameters beyond restating the same guidance, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes information from the knowledge base by point ID, using the verb 'delete' and resource 'knowledge base.' It distinguishes from siblings like search-knowledge and store-knowledge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to use the 'id' from search-knowledge results, providing a clear prerequisite and workflow context. It does not mention when not to use this tool, but the deletion purpose makes that largely implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-knowledge-by-idA

Retrieve specific knowledge items by their point IDs with full payload details. Use this to inspect complete information about stored items. Use the 'id' field returned from search-knowledge results.

ParametersJSON Schema
NameRequiredDescriptionDefault
idsYesA single point ID or a list of point IDs to retrieve. Use the 'id' from search-knowledge results.
collection_nameNoOptional collection to target; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions 'full payload details' but does not explain what happens with invalid IDs, whether the operation is read-only (implied but not stated), or any limits on the number of IDs. This is a significant gap for a fetch operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three succinct sentences, each serving a purpose: stating core functionality, clarifying the intent to inspect complete information, and providing operational guidance. It is front-loaded and contains no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema and complete parameter descriptions, the description successfully covers the essential dimensions of purpose and usage. However, because annotations are absent, some behavioral expectations (error handling, authentication) are left unaddressed, preventing a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by linking the 'ids' parameter directly to the 'id' field from search-knowledge, providing data flow context beyond what the schema offers. This elevates parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieve specific knowledge items by their point IDs' with 'full payload details', which distinguishes it from sibling tools like search-knowledge (which likely returns summaries) and store/delete operations. The verb 'retrieve' is specific and the resource is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it is for inspecting complete information about stored items, and explicitly directs the user to use the 'id' field from search-knowledge results. While it doesn't explicitly name alternatives or exclude other tools, the usage scenario is well established.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect-knowledge-baseA

Inspect the knowledge base configuration and view sample data. Useful for debugging collection settings or verifying stored content.

ParametersJSON Schema
NameRequiredDescriptionDefault
collection_nameNoOptional collection to inspect; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies a read operation via 'inspect' and 'view', but does not explicitly state that it is read-only, what exactly gets inspected (e.g., collection list, metadata, sample entries), or whether there are any side effects. This lack of disclosure is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the tool's purpose and followed by a practical use case. There is no redundant information, and every word contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple inspection tool with one optional parameter and an output schema, the description covers the core purpose and usage scenarios. It doesn't need to explain return values in detail because an output schema is present, though stating the read-only nature would have made it more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully describes the only parameter (collection_name with a default from env), and the description's reference to 'collection settings' aligns with the parameter. Since schema coverage is 100%, the description adds minimal extra value but is consistent with the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'inspects' the 'knowledge base configuration' and 'view sample data', which distinguishes it from sibling tools that store, search, get by ID, or delete knowledge. It is specific about what the tool does and what resource it operates on.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it is 'useful for debugging collection settings or verifying stored content', providing clear use cases. It does not explicitly mention when not to use it or alternatives, but the context is easily inferred from the sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-knowledgeA

Search for relevant information in the long-term knowledge base using semantic search. Use this to retrieve context, facts, or past interactions stored in Qdrant.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return (default: 5).
queryYesThe search query to find relevant information.
collection_nameNoOptional collection to target; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It mentions semantics search and Qdrant storage, indicating a read-only retrieval operation, but it doesn't describe any side effects, result ordering, or limitations. The presence of an output schema covers return values, but additional behavioral context like 'results are ranked by relevance' would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core action, and every word adds value. It wastes no space and is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's relative simplicity, an output schema, and full schema coverage, the description is mostly complete. It lacks a bit of behavioral nuance (e.g., that results are semantically ranked and not exact matches), but it serves its purpose for an agent to understand invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameter descriptions (100% coverage), so the baseline is 3. The description doesn't add parameter-specific meaning beyond what the schema already provides, though 'long-term knowledge base' hints at the collection context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Search for relevant information in the long-term knowledge base using semantic search,' which clearly identifies a specific verb (search), resource (long-term knowledge base), and method (semantic search). It distinguishes itself from siblings like store-knowledge and delete-knowledge by focusing on retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context with 'Use this to retrieve context, facts, or past interactions stored in Qdrant,' which indicates when to use the tool. It doesn't explicitly mention alternatives or when not to use it, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

store-knowledgeA

Store useful information or knowledge into the long-term knowledge base (Qdrant). This allows the agent to persist data that can be retrieved later or by other agents. Automatically embeds the text and returns the stored ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsNoOptional list of tags for categorization.
titleNoOptional title for the content, helpful for search context.
contentYesThe content to store in the knowledge base.
metadataNoOptional JSON metadata to attach.
collection_nameNoOptional collection to use; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable behaviors beyond a simple 'store' action: 'Automatically embeds the text and returns the stored ID.' This informs the agent about the embedding process and the return value. It does not mention edge cases like duplicate handling or potential errors, but for a store operation it is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and contains no filler. Every sentence adds value: the first states the core operation, the second explains the embedding and return ID. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description does not need to detail return values. It covers the core purpose, persistence semantics, and automatic embedding. It could mention storage prerequisites or default collection behavior, but the schema covers collection_name defaults. The description is sufficiently complete for an agent to decide to use this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents all parameters. The description adds only a reference to 'text' being embedded, which relates to the 'content' parameter but does not clarify tags, title, metadata, or collection_name beyond what the schema provides. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Store useful information or knowledge into the long-term knowledge base (Qdrant).' It also conveys persistence for later retrieval by the agent or other agents. However, it does not explicitly distinguish itself from the sibling 'store-knowledge-bulk' tool, leaving that differentiation to the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives implied usage context: 'This allows the agent to persist data that can be retrieved later or by other agents.' It does not explicitly state when to use this tool vs. alternatives, nor does it mention exclusions such as 'for bulk storage, use store-knowledge-bulk.' The guidance is present but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

store-knowledge-bulkA

Store multiple pieces of information or knowledge into the long-term knowledge base (Qdrant) at once. This is more efficient than calling store-knowledge multiple times. Each item is automatically embedded and stored with a unique ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
itemsYesList of knowledge items to store in the knowledge base.
collection_nameNoOptional collection to use; defaults to env COLLECTION_NAME.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses key behaviors: items are 'automatically embedded' and 'stored with a unique ID', plus the storage target (Qdrant). It does not cover error handling or idempotency, but the stated behaviors are meaningful and beyond what the schema provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The first sentence states the core purpose, the second adds efficiency context and behavioral detail. All information earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main usage scenario, efficiency over alternatives, and key behaviors. An output schema exists, so return values need not be described. It lacks details on failure modes or limits, but for a bulk store operation this is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema documents both items and collection_name. The description adds minimal parameter-specific meaning beyond mentioning 'items' implicitly; it does not explain collection_name, but the schema already covers it adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Store multiple pieces of information or knowledge into the long-term knowledge base (Qdrant) at once' – a specific verb and resource with clear bulk scope. It also differentiates from the sibling store-knowledge by noting it is more efficient than calling store-knowledge multiple times.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions an alternative ('more efficient than calling store-knowledge multiple times'), which implies use for batched storage. However, it does not explicitly state when NOT to use it (e.g., for a single item use store-knowledge) or other exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.4.2
    • First observeddelete-knowledge
    • First observedget-knowledge-by-id
    • First observedinspect-knowledge-base
    • First observedsearch-knowledge
    • First observedstore-knowledge
    • First observedstore-knowledge-bulk

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a distinct purpose: individual store, batch store, semantic search, get by ID, delete, and inspect. No overlap or ambiguity between them.

Naming Consistency4/5

Most tools follow a verb_knowledge pattern (store-knowledge, search-knowledge, delete-knowledge). store-knowledge-bulk is a minor deviation but still clear, and get-knowledge-by-id and inspect-knowledge-base are consistent with the verb_noun style.

Tool Count5/5

Six tools is well-scoped for a knowledge base server, covering the essential operations without bloat. Each tool earns its place.

Completeness4/5

Covers create (single and bulk), read (search, get by ID), delete, and inspect. No explicit update operation, but knowledge entries can be re-created; this is a minor gap.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    A lightweight MCP server that provides long-term memory for LLMs by storing and retrieving important facts, decisions, and preferences through smart semantic search and automatic organization.
    10
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jtsang4/better-qdrant-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server