MCP Memory Server with Qdrant Persistence
This MCP server provides a knowledge graph implementation with semantic search capabilities powered by Qdrant vector database.
Features
- Graph-based knowledge representation with entities and relations
- File-based persistence (memory.json)
- Semantic search using Qdrant vector database
- OpenAI embeddings for semantic similarity
- HTTPS support with reverse proxy compatibility
- Docker support for easy deployment
Environment Variables
The following environment variables are required:
# OpenAI API key for generating embeddings
OPENAI_API_KEY=your-openai-api-key
# Qdrant server URL (supports both HTTP and HTTPS)
QDRANT_URL=https://your-qdrant-server
# Qdrant API key (if authentication is enabled)
QDRANT_API_KEY=your-qdrant-api-key
# Name of the Qdrant collection to use
QDRANT_COLLECTION_NAME=your-collection-name
Setup
Local Setup
- Install dependencies:
- Build the server:
Docker Setup
- Build the Docker image:
docker build -t mcp-qdrant-memory .
- Run the Docker container with required environment variables:
docker run -d \
-e OPENAI_API_KEY=your-openai-api-key \
-e QDRANT_URL=http://your-qdrant-server:6333 \
-e QDRANT_COLLECTION_NAME=your-collection-name \
-e QDRANT_API_KEY=your-qdrant-api-key \
--name mcp-qdrant-memory \
mcp-qdrant-memory
Add to MCP settings:
{
"mcpServers": {
"memory": {
"command": "/bin/zsh",
"args": ["-c", "cd /path/to/server && node dist/index.js"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key",
"QDRANT_API_KEY": "your-qdrant-api-key",
"QDRANT_URL": "http://your-qdrant-server:6333",
"QDRANT_COLLECTION_NAME": "your-collection-name"
},
"alwaysAllow": [
"create_entities",
"create_relations",
"add_observations",
"delete_entities",
"delete_observations",
"delete_relations",
"read_graph",
"search_similar"
]
}
}
}
Entity Management
create_entities: Create multiple new entitiescreate_relations: Create relations between entitiesadd_observations: Add observations to entitiesdelete_entities: Delete entities and their relationsdelete_observations: Delete specific observationsdelete_relations: Delete specific relationsread_graph: Get the full knowledge graph
Semantic Search
search_similar: Search for semantically similar entities and relationsinterface SearchParams {
query: string; // Search query text
limit?: number; // Max results (default: 10)
}
Implementation Details
The server maintains two forms of persistence:
- File-based (memory.json):
- Complete knowledge graph structure
- Fast access to full graph
- Used for graph operations
- Qdrant Vector DB:
- Semantic embeddings of entities and relations
- Enables similarity search
- Automatically synchronized with file storage
Synchronization
When entities or relations are modified:
- Changes are written to memory.json
- Embeddings are generated using OpenAI
- Vectors are stored in Qdrant
- Both storage systems remain consistent
Search Process
When searching:
- Query text is converted to embedding
- Qdrant performs similarity search
- Results include both entities and relations
- Results are ranked by semantic similarity
Example Usage
// Create entities
await client.callTool("create_entities", {
entities: [{
name: "Project",
entityType: "Task",
observations: ["A new development project"]
}]
});
// Search similar concepts
const results = await client.callTool("search_similar", {
query: "development tasks",
limit: 5
});
HTTPS and Reverse Proxy Configuration
The server supports connecting to Qdrant through HTTPS and reverse proxies. This is particularly useful when:
- Running Qdrant behind a reverse proxy like Nginx or Apache
- Using self-signed certificates
- Requiring custom SSL/TLS configurations
Setting up with a Reverse Proxy
- Configure your reverse proxy (example using Nginx):
server {
listen 443 ssl;
server_name qdrant.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:6333;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
- Update your environment variables:
QDRANT_URL=https://qdrant.yourdomain.com
Security Considerations
The server implements robust HTTPS handling with:
- Custom SSL/TLS configuration
- Proper certificate verification options
- Connection pooling and keepalive
- Automatic retry with exponential backoff
- Configurable timeouts
Troubleshooting HTTPS Connections
If you experience connection issues:
- Verify your certificates:
openssl s_client -connect qdrant.yourdomain.com:443
- Test direct connectivity:
curl -v https://qdrant.yourdomain.com/collections
- Check for any proxy settings:
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
License
MIT