qdrant-api-mcp

v0.2.8

Published

18 days ago

Model Context Protocol server for Qdrant Collections & Points APIs

0High
0Medium
0Low

jordotech

qdrant mcp model-context-protocol vector

Qdrant MCP Server

A Model Context Protocol (MCP) server that wraps the Qdrant Collections and Points API. MCP tools are built straight from the official qdrant openapi schema files here: https://github.com/qdrant/qdrant/tree/master/openapi

Configure with Windsurf/Cursor

To use this tool with Windsurf or Cursor, add the following to your configuration:

{
  "mcpServers": {
    "qdrant-api": {
      "command": "node",
      "args": [
        "/<update-local-path>/qdrant-api-mcp/dist/mcp-server.js"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "my-secret-key-or-blank"
      }
    }
  }
}

The snippet above is the minimal setup and works for single-cluster projects. If you want the multi-cluster workflow described in the Quickstart section, configure Windsurf/Cursor with the exported cluster profile JSON string instead:

{
  "mcpServers": {
    "qdrant-api": {
      "command": "node",
      "args": [
        "/<update-local-path>/qdrant-api-mcp/dist/mcp-server.js"
      ],
      "env": {
        "QDRANT_CLUSTER_PROFILES": "[{\"name\":\"prod\",\"url\":\"https://prod.example\",\"apiKey\":\"***\",\"description\":\"Production search\"},{\"name\":\"metric-media\",\"url\":\"https://metric-media.example\",\"apiKey\":\"***\",\"labels\":[\"metrics\",\"readonly\"]},{\"name\":\"test\",\"url\":\"http://localhost:6333\"}]",
        "QDRANT_DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

Use via npx (no local checkout)

Prefer not to keep a local checkout? Once qdrant-api-mcp is published to npm you can have Windsurf/Cursor invoke it through npx:

{
  "mcpServers": {
    "qdrant-api": {
      "command": "npx",
      "args": ["qdrant-api-mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "my-secret-key-or-blank"
      }
    }
  }
}

The same approach works for the multi-cluster example—just reuse the JSON string for QDRANT_CLUSTER_PROFILES:

{
  "mcpServers": {
    "qdrant-api": {
      "command": "npx",
      "args": ["qdrant-api-mcp"],
      "env": {
        "QDRANT_CLUSTER_PROFILES": "[{\"name\":\"prod\",\"url\":\"https://prod.example\",\"apiKey\":\"***\",\"description\":\"Production search\"},{\"name\":\"metric-media\",\"url\":\"https://metric-media.example\",\"apiKey\":\"***\",\"labels\":[\"metrics\",\"readonly\"]},{\"name\":\"test\",\"url\":\"http://localhost:6333\"}]",
        "QDRANT_DEFAULT_CLUSTER": "prod"
      }
    }
  }
}

Inspect with MCP Inspector

Test the published package without editing config files by having MCP Inspector spawn the binary directly:

npx @modelcontextprotocol/inspector npx -y qdrant-api-mcp -e QDRANT_URL=http://localhost:6333

This downloads qdrant-api-mcp via npx, points it at your local Qdrant instance, and drops you into the Inspector CLI so you can call tools interactively.

Features

Implements the MCP JSON-RPC specification with structured JSON logs (Pino).
Responds to the MCP initialize handshake with cluster metadata so stdio and HTTP transports (Inspector, MCP runners) can connect without custom shims.
Resource discovery (resources/list, resources/read, resources/templates/list) advertises every configured cluster profile so MCP-aware tooling can “ping” the server before invoking tools.
Multi-cluster operation via optional QDRANT_CLUSTER_PROFILES and a switch_cluster tool. Change clusters without restarting the process.
Built-in request throttling (configurable via MCP_RATE_LIMIT_MAX_REQUESTS/MCP_RATE_LIMIT_WINDOW_MS) to prevent runaway hybrid queries.
Tools cover the full Collections/Points API plus new ergonomics:
- describe_point: combines payload, vector, and shard/cluster insights for a single point.
- scroll_points_paginated: emits resumable cursors for large scroll jobs.
- switch_cluster: inspects or updates the active cluster.
All existing collection & point tools remain available: list_collections, create_collection, get_collection, delete_collection, update_collection, upsert_points, search_points, scroll_points, count_points, recommend_points, get_point, delete_point, delete_points, set_payload, overwrite_payload, delete_payload, clear_payload.

Prerequisites

Node.js (v16 or higher)
npm or yarn
Qdrant server (local or remote)

Installation

Clone the repository
Install dependencies:

npm install

Configure environment variables in .env:

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_api_key_if_needed
PORT=3000
HOST=localhost

Quickstart

Install dependencies and compile once:
```
npm install
npm run build
```
Point your MCP-compatible IDE/agent at the compiled entrypoint (dist/mcp-server.js) or run the published binary directly with npx qdrant-api-mcp. A sample config lives in qdrant-mcp-config.json.
```
QDRANT_URL=http://localhost:6333 npx qdrant-api-mcp
```

(Optional) Define multiple clusters in your environment:

export QDRANT_CLUSTER_PROFILES='[
  {"name":"prod","url":"https://prod.example","apiKey":"***","description":"Production search"},
  {"name":"metric-media","url":"https://metric-media.example","apiKey":"***","labels":["metrics","readonly"]},
  {"name":"test","url":"http://localhost:6333"}
]'
export QDRANT_DEFAULT_CLUSTER=prod

Launch the MCP server (dev hot reload shown):
```
npm run dev:mcp
```
From your MCP client, call switch_cluster (with no args) to verify the active cluster, or provide {"cluster":"test"} to pivot to a different backend without restarting.

Usage

Development

Run the server in development mode:

npm run dev

Production

Build and run the server:

npm run build
npm start

Testing

Integration tests run against a lightweight mock Qdrant server:

npm test

Use npm run test:watch for a persistent Vitest watcher while iterating locally.

Operational safeguards & logging

Rate limiting: MCP_RATE_LIMIT_MAX_REQUESTS (default 10) and MCP_RATE_LIMIT_WINDOW_MS (default 1000) bound the number of tool calls per cluster/tool combination. Tune these per environment to protect production clusters from runaway agents.
Structured logs: Set LOG_LEVEL=debug (or info, warn, etc.). Each MCP tool call is logged with {event, tool, cluster, durationMs} so Qdrant audit events can be correlated easily.
Resource discovery: resources/list advertises every configured cluster as qdrant://clusters/<name>. Reading the resource returns a JSON overview (active flag, collection preview, rate limits, safety hints).

Sample MCP tool calls

Switch clusters without restarting the process:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "switch_cluster",
    "arguments": { "cluster": "metric-media" }
  }
}

Resume a long scroll using the new pagination helper:

{
  "jsonrpc": "2.0",
  "id": 99,
  "method": "tools/call",
  "params": {
    "name": "scroll_points_paginated",
    "arguments": {
      "collection_name": "hybrid-docs",
      "limit": 128,
      "with_payload": true
    }
  }
}

The response includes cursor; feed it back into the next call to continue from the previous next_page_offset.

Deep dive into a single point (payload + vector + shard metadata):

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "describe_point",
    "arguments": {
      "cluster": "prod",
      "collection_name": "docs",
      "point_id": "doc-123"
    }
  }
}

Best practices for production clusters

Keep destructive tools (collection/point mutation) disabled unless you have explicit approval for the target environment. The sample config only whitelists read-only tools by default.
Use switch_cluster to make sure you are operating on the intended cluster before issuing search/scroll commands.
Lower MCP_RATE_LIMIT_MAX_REQUESTS for clusters that back user-facing workloads.
Scrub or truncate payload data before pasting MCP responses into bug reports—cluster resources can include sensitive labels.
Rotate API keys regularly and store them only in environment variables; the MCP resource summaries intentionally omit raw credentials.

API Endpoints

MCP JSON-RPC Endpoint

POST /mcp: The main MCP JSON-RPC endpoint
POST /<server-name>/mcp: Alternate path for HTTP proxies (e.g., fastmcp runner); the server automatically accepts a leading slug.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "list_collections",
  "params": {}
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "collections": ["collection1", "collection2"]
  }
}

Health Check

GET /health: Returns server health status
GET /<server-name>/health: Health endpoint behind an HTTP slug

Available Methods

list_collections

Lists all collections.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "list_collections",
  "params": {}
}

create_collection

Creates a new collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_collection",
  "params": {
    "collection_name": "my_collection",
    "vectors": {
      "size": 384,
      "distance": "Cosine"
    }
  }
}

get_collection

Gets detailed information about a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_collection",
  "params": {
    "collection_name": "my_collection"
  }
}

delete_collection

Deletes a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delete_collection",
  "params": {
    "collection_name": "my_collection"
  }
}

update_collection

Updates collection parameters.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "update_collection",
  "params": {
    "collection_name": "my_collection",
    "optimizers_config": {
      "deleted_threshold": 0.2,
      "vacuum_min_vector_number": 1000
    }
  }
}

Points Operations

upsert_points

Insert or update points in a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "upsert_points",
  "params": {
    "collection_name": "my_collection",
    "points": [
      {
        "id": 1,
        "vector": [0.1, 0.2, 0.3, 0.4],
        "payload": {
          "category": "example",
          "value": 42
        }
      }
    ]
  }
}

search_points

Search for similar points in a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "search_points",
  "params": {
    "collection_name": "my_collection",
    "vector": [0.1, 0.2, 0.3, 0.4],
    "limit": 10,
    "with_payload": true,
    "with_vector": false
  }
}

scroll_points

Scroll through points in a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "scroll_points",
  "params": {
    "collection_name": "my_collection",
    "limit": 10,
    "with_payload": true
  }
}

count_points

Count points in a collection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "count_points",
  "params": {
    "collection_name": "my_collection",
    "filter": {
      "must": [
        {
          "key": "category",
          "match": {
            "value": "example"
          }
        }
      ]
    }
  }
}

recommend_points

Get point recommendations based on positive and negative examples.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "recommend_points",
  "params": {
    "collection_name": "my_collection",
    "positive": [1, 2],
    "negative": [3],
    "limit": 10
  }
}

Project Structure

qdrant_mcp/
├── src/
│   ├── api/            # API-related code (for future expansion)
│   ├── config/         # Configuration files
│   ├── generated/      # Generated client code
│   ├── lib/            # Library code (Qdrant client)
│   ├── mcp/            # MCP server implementation
│   ├── types/          # TypeScript type definitions
│   └── index.ts        # Application entry point
├── .env                # Environment variables
├── .gitignore          # Git ignore file
├── package.json        # Project dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation