MCP Qdrant Bridge

A client bridge for connecting Cursor IDE or Claude Desktop to remote Qdrant RAG (Retrieval-Augmented Generation) servers via the Model Context Protocol (MCP).

What is This?

This package allows you to connect your local Cursor IDE or Claude Desktop to a remote Qdrant vector database server for semantic search over your documents. It acts as a bridge that:

1. Runs locally on your machine (required by Cursor's MCP implementation)
2. Forwards requests to your remote HTTP API server
3. Returns results back to Cursor/Claude

Installation

Quick Start (with npx - Recommended)

No installation needed! Just configure in your Cursor/Claude config:

Cursor: Edit ~/.cursor/mcp.json (or %USERPROFILE%\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "http://your-server.com:3006",
        "MCP_USER_ID": "user_123"
      }
    }
  }
}

Claude Desktop: Edit your Claude config file:

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

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "http://your-server.com:3006",
        "MCP_USER_ID": "user_123"
      }
    }
  }
}

Global Installation (Optional)

If you prefer to install globally:

npm install -g mcp-qdrant-bridge

Then use in config:

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "mcp-qdrant-bridge",
      "args": [],
      "env": {
        "MCP_API_URL": "http://your-server.com:3006",
        "MCP_USER_ID": "user_123"
      }
    }
  }
}

Configuration

Required Environment Variables

• MCP_API_URL - The URL of your remote Qdrant RAG server (e.g., http://178.156.131.249:3006)

Optional Environment Variables

• MCP_USER_ID or MCP_COLLECTION_NAME - Default collection name to query. If not set, you must provide collectionName parameter in each query.

Example Configurations

Local Testing

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "http://localhost:3006",
        "MCP_USER_ID": "test_collection"
      }
    }
  }
}

Production Server

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "https://api.example.com:3006",
        "MCP_USER_ID": "user_33WMlIo4So5vEOsTSU4xHvXJ4vI"
      }
    }
  }
}

Multiple Collections

{
  "mcpServers": {
    "qdrant-docs": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "http://your-server.com:3006",
        "MCP_USER_ID": "docs_collection"
      }
    },
    "qdrant-code": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-bridge"],
      "env": {
        "MCP_API_URL": "http://your-server.com:3006",
        "MCP_USER_ID": "code_collection"
      }
    }
  }
}

Usage

Once configured, restart Cursor or Claude Desktop. The MCP tools will be available:

Available Tools

1. query_rag

Search your document collection using natural language queries.

Parameters:

• query (required): Your search query
• collectionName (optional): Collection to search (defaults to MCP_USER_ID)
• limit (optional): Max results (1-100, default: 10)
• scoreThreshold (optional): Min similarity score (0-1, default: 0.5)
• filterUrl (optional): Filter by URL pattern
• filterTitle (optional): Filter by title pattern

Example usage in Cursor/Claude:

Search my documentation for authentication

Find information about pricing in my docs, limit to 5 results

Query my scraped content about API endpoints with a similarity threshold of 0.7

2. list_collections

List all available collections on the remote server.

Example usage:

List all available collections

Setting Up the Remote Server

This bridge requires a compatible remote server. You can use the reference implementation:

1. Clone the server repository
2. Install dependencies: npm install
3. Set environment variables:

   OPENAI_API_KEY=sk-your-key
   QDRANT_URL=http://localhost:6333
   PORT=3006

4. Start the server: npm run server

The server should expose these endpoints:

• GET /health - Health check
• GET /collections - List collections
• POST /query_rag - RAG query endpoint

Troubleshooting

"MCP_API_URL environment variable is required"

Make sure you've set the MCP_API_URL in your config file's env section.

"Could not connect to remote API"

1. Check if the remote server is running
2. Verify the URL is correct (including port number)
3. Ensure firewall allows connections
4. Test with curl: curl http://your-server:3006/health

"Collection not found"

1. List available collections using the list_collections tool
2. Ensure your MCP_USER_ID matches an existing collection
3. Or provide the correct collectionName parameter in your query

No Results

1. Try lowering scoreThreshold (e.g., from 0.5 to 0.3)
2. Verify content exists in the collection
3. Check that your query is relevant to the indexed content

Cursor/Claude Not Showing Tools

1. Restart Cursor/Claude Desktop after config changes
2. Check the logs for errors:
   • Cursor: %APPDATA%\Cursor\logs\ or ~/.cursor/logs/
   • Claude: Look for MCP-related logs in app directory
3. Verify JSON syntax in config file

How It Works

┌─────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   Cursor    │ stdio   │  mcp-qdrant-     │  HTTP   │  Remote Server   │
│   or        │────────▶│  bridge          │────────▶│  (API)           │
│   Claude    │         │  (Local Process) │         │                  │
└─────────────┘         └──────────────────┘         └─────────┬────────┘
                                                               │
                                                               ▼
                                                      ┌─────────────────┐
                                                      │ Qdrant + OpenAI │
                                                      └─────────────────┘

1. Cursor/Claude spawns mcp-qdrant-bridge as a local process
2. Bridge communicates with Cursor/Claude via stdio (standard input/output)
3. Bridge forwards requests to remote HTTP API
4. Remote Server processes queries using Qdrant and OpenAI
5. Results flow back through the bridge to Cursor/Claude

Features

• ✅ Easy installation via npx (no manual setup needed)
• ✅ Works with Cursor IDE and Claude Desktop
• ✅ Connects to remote Qdrant servers
• ✅ Full RAG query support with configurable parameters
• ✅ Collection listing and management
• ✅ Detailed logging for debugging
• ✅ Graceful error handling

Requirements

• Node.js 18 or higher
• A compatible remote MCP server with Qdrant RAG capabilities
• Cursor IDE or Claude Desktop

License

MIT

Support

For issues or questions:

• Check the troubleshooting section above
• Review server logs for detailed error messages
• Ensure your remote server is properly configured and accessible

Related Projects

• Model Context Protocol
• Qdrant Vector Database
• Cursor IDE
• Claude Desktop