mcp-qdrant-memory

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

1. Install dependencies:

npm install

2. Build the server:

npm run build

Docker Setup

1. Build the Docker image:

docker build -t mcp-qdrant-memory .

2. 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"
      ]
    }
  }
}

Tools

Entity Management

• create_entities: Create multiple new entities
• create_relations: Create relations between entities
• add_observations: Add observations to entities
• delete_entities: Delete entities and their relations
• delete_observations: Delete specific observations
• delete_relations: Delete specific relations
• read_graph: Get the full knowledge graph

Semantic Search

• search_similar: Search for semantically similar entities and relations

  interface SearchParams {
    query: string;     // Search query text
    limit?: number;    // Max results (default: 10)
  }

  Copy

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

1. 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;
    }
}

2. 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:

1. Verify your certificates:

openssl s_client -connect qdrant.yourdomain.com:443

2. Test direct connectivity:

curl -v https://qdrant.yourdomain.com/collections

3. Check for any proxy settings:

env | grep -i proxy

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT