Qdrant Knowledge Graph MCP server for AI agents

This MCP server provides a knowledge graph implementation with semantic search capabilities powered by Qdrant vector database. It combines graph-based knowledge representation with powerful semantic search to help you organize and retrieve information more effectively.

Environment Setup

You'll need to configure the following environment variables before starting:

# 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

Installation Options

Local Installation

To set up the server locally:

Install dependencies:

npm install

Build the server:

npm run build

Run the server:

node dist/index.js

Docker Installation

For a containerized 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

MCP Integration

Add the following configuration to your MCP settings file:

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

Available 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

Use the search_similar tool to find semantically similar entities and relations:

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

Usage Examples

Creating Entities

await client.callTool("create_entities", {
  entities: [{
    name: "Project",
    entityType: "Task",
    observations: ["A new development project"]
  }]
});

Searching for Similar Concepts

const results = await client.callTool("search_similar", {
  query: "development tasks",
  limit: 5
});

HTTPS and Reverse Proxy Support

The server supports connecting to Qdrant through HTTPS and reverse proxies, which is useful when:

Running Qdrant behind Nginx or Apache
Using self-signed certificates
Requiring custom SSL/TLS configurations

Setting Up with Nginx

Configure your Nginx reverse proxy:

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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect