Metadata-Version: 2.3
Name: better-qdrant-mcp
Version: 0.3.1
Summary: A Python MCP server for Qdrant memory storage and semantic search, compatible with Cursor-like MCP clients.
Keywords: mcp,model-context-protocol,qdrant,vector-database,semantic-search,memory
Author: jtsang4
Author-email: jtsang4 <info@jtsang.me>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: fastembed>=0.7.3
Requires-Dist: fastmcp>=2.13.1
Requires-Dist: jieba>=0.42.1
Requires-Dist: openai>=1.47.0
Requires-Dist: qdrant-client>=1.15.1
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: starlette>=0.40.0
Requires-Python: >=3.12
Project-URL: Documentation, https://github.com/jtsang4/better-qdrant-mcp#readme
Project-URL: Homepage, https://github.com/jtsang4/better-qdrant-mcp
Project-URL: Issues, https://github.com/jtsang4/better-qdrant-mcp/issues
Project-URL: Repository, https://github.com/jtsang4/better-qdrant-mcp
Description-Content-Type: text/markdown

# 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
- **Three tools** aligned with the Node.js version:
  - `memory-store`
  - `memory-search`
  - `memory-debug`
- **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_TRANSPORT` – `stdio` | `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 three tools:

- `memory-store(information, metadata?: dict, collection_name?: str) -> str`
- `memory-search(query, limit?: int=5, collection_name?: str) -> str`
- `memory-debug(collection_name?: str) -> str`

`memory-search` 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.

#### 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

```bash
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)

```bash
# 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`)

##### Streamable HTTP (recommended for web applications)

```bash
# 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`)

## Development Guide

### Local installation (for development)

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

```bash
# using uv (recommended)
uv sync

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

### Local build

For local development, you can use the provided `Makefile`:

```bash
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**.

```bash
# 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](LICENSE)
