Qdrant MCP Server Cursor IDE Setup (2026): uvx Install, QDRANT_URL & Local-Path Config
Connect Qdrant's official MCP server to Cursor IDE: install with uvx (not npx), set QDRANT_URL or QDRANT_LOCAL_PATH plus COLLECTION_NAME, and store or retrieve memories with the qdrant-store and qdrant-find tools — including why this one needs Python's uv, not Node.
Qdrant MCP Server Cursor IDE Setup (2026)
How do you connect Qdrant to Cursor? Install uv if you don't already have it, add a qdrant entry to ~/.cursor/mcp.json that runs mcp-server-qdrant via uvx, and set QDRANT_URL (or QDRANT_LOCAL_PATH for an on-disk database) plus COLLECTION_NAME in its env block. Restart Cursor, and it can store notes into a Qdrant collection and retrieve them later by semantic similarity — two tools, qdrant-store and qdrant-find, nothing more.
That narrow scope is the point. Qdrant's official server isn't a general vector-database admin panel — it's built specifically as an AI memory layer: a place for an agent to write things down and search for them later by meaning rather than keyword. If you want full collection management (create/delete collections, configure distance metrics, inspect payloads), you'll still reach for Qdrant's own client SDK or the Qdrant Cloud console; this MCP server covers store-and-recall, not administration.
If you're evaluating vector databases for MCP-driven retrieval, the Pinecone MCP server guide covers the equivalent setup for Pinecone's managed offering — useful for comparing the two before you commit to one.
What the Qdrant MCP Server Can Do
Once connected, typical prompts include:
Under the hood, qdrant-store embeds whatever text you give it (using the model set in EMBEDDING_MODEL) and writes it into the configured collection with any metadata you attach. qdrant-find embeds your query the same way and returns the closest matches by vector similarity — a real semantic search, not a substring match.
The Part Every Other Guide on This Site Skips: This Isn't an npx Server
Nearly every MCP server on this site installs the same way — npx -y <package> in the command/args fields. Qdrant's official server doesn't; it's a Python package distributed for uv, run via uvx rather than npx. If you copy-paste a command: "npx" block from another guide and swap in mcp-server-qdrant, it will fail — that package isn't published to npm at all.
Install uv first if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh
(Or brew install uv on macOS.) Confirm it's on your PATH with uvx --version before touching mcp.json — a missing uv install is the single most common reason this server fails to start, and Cursor's error surfaces as a generic "server failed to start" rather than "command not found."
Prerequisites
uv installed and on your PATH (not Node.js — this server doesn't need it)Step 1: Decide Remote vs. Local Storage
Qdrant's server supports two mutually exclusive storage modes, and the README is explicit that you can't set both at once:
QDRANT_URL — point at a running Qdrant server, self-hosted or Qdrant Cloud. Use this if you already run Qdrant, or want the data to outlive any single machine.QDRANT_LOCAL_PATH — a filesystem path where Qdrant stores an embedded, on-disk database. No server to run at all — good for a personal, single-machine memory store.Setting both in the same env block causes the server to fail on startup with a config conflict.
Step 2: Configure Cursor MCP
Remote Qdrant (self-hosted or Cloud):
{
"mcpServers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
"QDRANT_API_KEY": "your_api_key",
"COLLECTION_NAME": "cursor-memory",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
}
QDRANT_API_KEY is only required for Qdrant Cloud or a self-hosted instance you've secured with one — a bare local Docker instance with no auth configured doesn't need it.
Local, on-disk database:
{
"mcpServers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_LOCAL_PATH": "/Users/you/.qdrant/cursor-memory",
"COLLECTION_NAME": "cursor-memory",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
}
COLLECTION_NAME is required either way — the server needs a default collection to write to when a prompt doesn't specify one. EMBEDDING_MODEL defaults to sentence-transformers/all-MiniLM-L6-v2 (via the fastembed provider) if you omit it, so it's optional but worth setting explicitly if you're comparing results across a schema change later.
Restart Cursor after saving.
Step 3: Test the Connection
In Cursor chat:
Remember that our API rate limit for the /search endpoint is 100 requests per minute per API key
Then in a fresh conversation:
What do you know about our API rate limits?
If the second prompt surfaces the fact you stored in the first — even phrased differently, since this is semantic search, not exact match — the connection is working.
A Gotcha With Local Mode: First Run Downloads a Model
The first time qdrant-store or qdrant-find runs with the default fastembed provider, it downloads the embedding model (a few hundred MB) before it can embed anything. On a slow connection, or in a sandboxed CI environment with no outbound network, that first call can time out or hang rather than erroring cleanly. If your first test prompt seems to stall, give it a minute before assuming the config is wrong — check for a .fastembed_cache or similar directory appearing under the process's working directory as a sign it's actually downloading, not stuck.
Troubleshooting
"uvx: command not found"uv isn't installed, or isn't on the PATH Cursor's process sees (which can differ from your shell's PATH, especially on macOS if Cursor was launched from the Dock rather than a terminal). Reinstall uv and fully quit-and-reopen Cursor, not just restart the chat panel.
Server starts but every store/find call fails with a connection error
For remote mode, confirm QDRANT_URL includes the port (:6333 for HTTP, :6334 for gRPC) and that nothing between your machine and the Qdrant instance — a corporate VPN, a Docker network boundary — is blocking it. Test with curl QDRANT_URL/collections directly to isolate whether it's a Qdrant-reachability issue or an MCP config issue.
"Both QDRANT_URL and QDRANT_LOCAL_PATH cannot be provided"
Delete whichever mode you're not using from the env block — the server refuses to start with both set, by design, since it can't guess which storage backend you meant.
Collection doesn't exist yet
Unlike some vector-DB integrations, this server creates the collection specified in COLLECTION_NAME automatically on first write if it doesn't already exist — you don't need to pre-create it through the Qdrant console or CLI first.
Results come back but don't seem relevant
Semantic search quality depends on the embedding model matching your content's language and domain. The default all-MiniLM-L6-v2 is a small, general-purpose English model — fine for short notes and facts, weaker on long technical documents or non-English content. If relevance is consistently off, that's a model choice to revisit, not a connection bug.
When Not to Use This
This server has no delete or update tools exposed — it's append-and-search by design, which means stale or wrong information you stored earlier doesn't get corrected by storing a newer fact; both versions sit in the collection and the search just returns whichever is more similar to your query. For a memory store that needs corrections over time, periodically review what's actually in the collection through Qdrant's own console rather than assuming MCP-stored facts self-update.
Frequently Asked Questions
Q: Why does this server use uvx instead of npx like most MCP servers?
A: It's a Python package, not a Node one — mcp-server-qdrant is published for uv/pip, not npm. Every other setup step (the mcp.json block, the command/args/env structure) works the same way Cursor expects; only the runtime and install command differ.
Q: Do I need a running Qdrant server, or can I use this without one?
A: You need either a running Qdrant instance (QDRANT_URL) or a local on-disk path (QDRANT_LOCAL_PATH) — the server itself doesn't ship an embedded database with zero configuration. Local mode is the lower-friction option if you don't already run Qdrant somewhere.
Q: What's the difference between this and the Pinecone MCP server?
A: Different products with a similar shape. Pinecone's MCP server is scoped to Pinecone's integrated-inference indexes and includes documentation search even without an API key; Qdrant's is a minimal store/find memory layer that works equally well against a free self-hosted instance or Qdrant Cloud. If you're already running one of the two databases, use that one's guide — see the Pinecone MCP server setup for the alternative.
Q: Can Cursor delete or update something it stored earlier?
A: No — the official server only exposes qdrant-store and qdrant-find. There's no delete or update tool, so corrections require going into the Qdrant console or CLI directly rather than asking the AI to fix a stored fact.
Q: Does this work with a free, self-hosted Qdrant instance, or does it require Qdrant Cloud?
A: Either works. Point QDRANT_URL at http://localhost:6333 (or wherever your Docker instance listens) for self-hosted, with QDRANT_API_KEY only if you've configured auth on that instance. Qdrant Cloud requires the API key.
Q: Can I use a different embedding model than the default?
A: Yes, set EMBEDDING_MODEL to any model supported by the fastembed provider — the server currently only supports fastembed-compatible models, not an arbitrary OpenAI or Cohere embeddings API, so check fastembed's supported model list before picking one your content actually needs.
Related Guides
---