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:

npm install

Build the server:

npm run build

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

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) }

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:

env | grep -i proxy

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT

MCP Memory Server with Qdrant Persistence

Integrations

MCP Memory Server with Qdrant Persistence

Features

Environment Variables

Setup

Local Setup

Docker Setup

Add to MCP settings:

Tools

Entity Management

Semantic Search

Implementation Details

Synchronization

Search Process

Example Usage

HTTPS and Reverse Proxy Configuration

Setting up with a Reverse Proxy

Security Considerations

Troubleshooting HTTPS Connections

Contributing

License

Related Resources