Qdrant MCP Server

ทางการ

ใช้ชั้นความจำเชิงความหมายบนเครื่องมือค้นหาเวกเตอร์ Qdrant

เอกสาร

mcp-server-qdrant: เซิร์ฟเวอร์ MCP สำหรับ Qdrant

Model Context Protocol (MCP) เป็นโปรโตคอลแบบเปิดที่ช่วยให้ การผสานรวมระหว่างแอปพลิเคชัน LLM กับแหล่งข้อมูลและเครื่องมือภายนอกเป็นไปอย่างราบรื่น ไม่ว่าคุณจะกำลังสร้าง IDE ที่ขับเคลื่อนด้วย AI, ปรับปรุงอินเทอร์เฟซแชท, หรือสร้างเวิร์กโฟลว์ AI แบบกำหนดเอง MCP มอบวิธีที่เป็นมาตรฐานในการ เชื่อมต่อ LLM กับบริบทที่พวกเขาต้องการ

ที่เก็บนี้เป็นตัวอย่างวิธีการสร้างเซิร์ฟเวอร์ MCP สำหรับ Qdrant ซึ่งเป็นเอนจินค้นหาแบบเวกเตอร์

ภาพรวม

เซิร์ฟเวอร์ Model Context Protocol อย่างเป็นทางการสำหรับการเก็บและเรียกคืนความทรงจำในเอนจินค้นหาแบบเวกเตอร์ Qdrant มันทำหน้าที่เป็นเลเยอร์หน่วยความจำเชิงความหมายบนฐานข้อมูล Qdrant

ส่วนประกอบ

เครื่องมือ

qdrant-store
- จัดเก็บข้อมูลบางอย่างในฐานข้อมูล Qdrant
- อินพุต:
  - information (สตริง): ข้อมูลที่จะจัดเก็บ
  - metadata (JSON): เมทาดาทาเสริมที่จะจัดเก็บ
  - collection_name (สตริง): ชื่อของคอลเลกชันที่จะจัดเก็บข้อมูล ฟิลด์นี้จำเป็นหากไม่มีชื่อคอลเลกชันเริ่มต้น หากมีชื่อคอลเลกชันเริ่มต้น ฟิลด์นี้จะไม่ถูกเปิดใช้งาน
- ส่งคืน: ข้อความยืนยัน
qdrant-find
- เรียกคืนข้อมูลที่เกี่ยวข้องจากฐานข้อมูล Qdrant
- อินพุต:
  - query (สตริง): คำค้นหาที่ใช้สำหรับการค้นหา
  - collection_name (สตริง): ชื่อของคอลเลกชันที่จะจัดเก็บข้อมูล ฟิลด์นี้จำเป็นหากไม่มีชื่อคอลเลกชันเริ่มต้น หากมีชื่อคอลเลกชันเริ่มต้น ฟิลด์นี้จะไม่ถูกเปิดใช้งาน
- ส่งคืน: ข้อมูลที่จัดเก็บในฐานข้อมูล Qdrant เป็นข้อความแยกกัน

ตัวแปรสภาพแวดล้อม

การกำหนดค่าทำผ่านตัวแปรสภาพแวดล้อม อาร์กิวเมนต์บรรทัดคำสั่งเดียวคือ --transport ซึ่งใช้เพื่อเลือก โปรโตคอลการขนส่ง

[!NOTE] คุณไม่สามารถระบุทั้ง QDRANT_URL และ QDRANT_LOCAL_PATH พร้อมกันได้

ชื่อ	คำอธิบาย	ค่าเริ่มต้น
`QDRANT_URL`	URL ของเซิร์ฟเวอร์ Qdrant	ไม่มี
`QDRANT_API_KEY`	คีย์ API สำหรับเซิร์ฟเวอร์ Qdrant	ไม่มี
`COLLECTION_NAME`	ชื่อของคอลเลกชันเริ่มต้นที่จะใช้	ไม่มี
`QDRANT_LOCAL_PATH`	พาธไปยังฐานข้อมูล Qdrant ภายในเครื่อง (ทางเลือกแทน `QDRANT_URL`)	ไม่มี
`EMBEDDING_PROVIDER`	ผู้ให้บริการเอมเบ็ดดิ้งที่จะใช้ (ปัจจุบันรองรับเฉพาะ "fastembed")	`fastembed`
`EMBEDDING_MODEL`	ชื่อของโมเดลเอมเบ็ดดิ้งที่จะใช้	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	คำอธิบายแบบกำหนดเองสำหรับเครื่องมือจัดเก็บ	ดูค่าเริ่มต้นใน `settings.py`
`TOOL_FIND_DESCRIPTION`	คำอธิบายแบบกำหนดเองสำหรับเครื่องมือค้นหา	ดูค่าเริ่มต้นใน `settings.py`
`QDRANT_SEARCH_LIMIT`	จำนวนผลลัพธ์สูงสุดที่จะส่งคืนจากการค้นหา	`10`
`QDRANT_READ_ONLY`	เปิดใช้งานโหมดอ่านอย่างเดียว (ปิดใช้งานเครื่องมือ `qdrant-store`)	`false`

ตัวแปรสภาพแวดล้อม FastMCP

เนื่องจาก mcp-server-qdrant สร้างบน FastMCP มันจึงรองรับตัวแปรสภาพแวดล้อมทั้งหมดของ FastMCP ด้วย ตัวแปรที่สำคัญ ที่สุดแสดงไว้ด้านล่าง:

ตัวแปรสภาพแวดล้อม	คำอธิบาย	ค่าเริ่มต้น
`FASTMCP_LOG_LEVEL`	ตั้งค่าระดับการบันทึก (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	เปิดใช้งานโหมดดีบัก	`false`
`FASTMCP_SERVER_HOST`	ที่อยู่โฮสต์ที่จะผูกเซิร์ฟเวอร์	`127.0.0.1`
`FASTMCP_SERVER_PORT`	พอร์ตที่จะรันเซิร์ฟเวอร์	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	ลักษณะการทำงานสำหรับทรัพยากรที่ซ้ำกัน (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	ลักษณะการทำงานสำหรับเครื่องมือที่ซ้ำกัน (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	ลักษณะการทำงานสำหรับพรอมต์ที่ซ้ำกัน (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	รายการการพึ่งพาที่จะติดตั้งในสภาพแวดล้อมเซิร์ฟเวอร์	`[]`

[!NOTE] การตั้งค่าเฉพาะเซิร์ฟเวอร์ใช้คำนำหน้า FASTMCP_SERVER_ ซึ่งอาจเปลี่ยนแปลงในเวอร์ชันอนาคต

การติดตั้ง

การใช้ uvx

เมื่อใช้ uvx ไม่จำเป็นต้องติดตั้งเฉพาะเพื่อรัน mcp-server-qdrant โดยตรง

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

โปรโตคอลการขนส่ง

เซิร์ฟเวอร์รองรับโปรโตคอลการขนส่งที่แตกต่างกันซึ่งสามารถระบุได้โดยใช้แฟล็ก --transport:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

โปรโตคอลการขนส่งที่รองรับ:

stdio (ค่าเริ่มต้น): การขนส่งอินพุต/เอาต์พุตมาตรฐาน อาจใช้โดยไคลเอนต์ MCP ภายในเครื่องเท่านั้น
sse: การขนส่ง Server-Sent Events เหมาะสำหรับไคลเอนต์ระยะไกล
streamable-http: การขนส่ง HTTP แบบสตรีมได้ เหมาะสำหรับไคลเอนต์ระยะไกล ใหม่กว่า SSE

การขนส่งเริ่มต้นคือ stdio หากไม่ได้ระบุ

เมื่อใช้การขนส่ง SSE เซิร์ฟเวอร์จะรอรับการเชื่อมต่อขาเข้าบนพอร์ตที่ระบุ พอร์ตเริ่มต้น คือ 8000 อย่างไรก็ตามสามารถเปลี่ยนแปลงได้โดยใช้ตัวแปรสภาพแวดล้อม FASTMCP_SERVER_PORT

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

การใช้ Docker

มี Dockerfile สำหรับการสร้างและรันเซิร์ฟเวอร์ MCP:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_HOST="0.0.0.0" \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

[!TIP] โปรดทราบว่าเราตั้งค่า FASTMCP_SERVER_HOST="0.0.0.0" เพื่อให้เซิร์ฟเวอร์รับฟังบนอินเทอร์เฟซเครือข่ายทั้งหมด นี่เป็น สิ่งจำเป็นเมื่อรันเซิร์ฟเวอร์ในคอนเทนเนอร์ Docker

การติดตั้งผ่าน Smithery

เพื่อติดตั้ง Qdrant MCP Server สำหรับ Claude Desktop โดยอัตโนมัติผ่าน Smithery:

npx @smithery/cli install mcp-server-qdrant --client claude

การกำหนดค่า Claude Desktop ด้วยตนเอง

เพื่อใช้เซิร์ฟเวอร์นี้กับแอป Claude Desktop ให้เพิ่มการกำหนดค่าต่อไปนี้ในส่วน "mcpServers" ของ claude_desktop_config.json ของคุณ:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
      "QDRANT_API_KEY": "your_api_key",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

สำหรับโหมด Qdrant ภายในเครื่อง:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

เซิร์ฟเวอร์ MCP นี้จะสร้างคอลเลกชันด้วยชื่อที่ระบุโดยอัตโนมัติหากยังไม่มี

โดยค่าเริ่มต้น เซิร์ฟเวอร์จะใช้โมเดลเอมเบ็ดดิ้ง sentence-transformers/all-MiniLM-L6-v2 เพื่อเข้ารหัสความทรงจำ ในขณะนี้ รองรับเฉพาะโมเดล FastEmbed เท่านั้น

การสนับสนุนเครื่องมืออื่นๆ

เซิร์ฟเวอร์ MCP นี้สามารถใช้กับไคลเอนต์ที่เข้ากันได้กับ MCP ใดๆ ตัวอย่างเช่น คุณสามารถใช้กับ Cursor และ VS Code ซึ่งมีการสนับสนุนในตัวสำหรับ Model Context Protocol

การใช้กับ Cursor/Windsurf

คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP นี้ให้ทำงานเป็นเครื่องมือค้นหาโค้ดสำหรับ Cursor หรือ Windsurf โดยปรับแต่งคำอธิบาย เครื่องมือ:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport

ใน Cursor/Windsurf คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP ในการตั้งค่าของคุณโดยชี้ไปยังเซิร์ฟเวอร์ที่กำลังรันนี้โดยใช้ โปรโตคอลการขนส่ง SSE คำอธิบายเกี่ยวกับวิธีการเพิ่มเซิร์ฟเวอร์ MCP ไปยัง Cursor สามารถพบได้ใน เอกสารประกอบ Cursor หากคุณ กำลังรัน Cursor/Windsurf ภายในเครื่อง คุณสามารถใช้ URL ต่อไปนี้:

http://localhost:8000/sse

[!TIP] เราแนะนำการขนส่ง SSE เป็นวิธีที่ต้องการในการเชื่อมต่อ Cursor/Windsurf กับเซิร์ฟเวอร์ MCP เนื่องจากสามารถรองรับการเชื่อมต่อ ระยะไกลได้ ทำให้ง่ายต่อการแชร์เซิร์ฟเวอร์กับทีมของคุณหรือใช้ในสภาพแวดล้อมคลาวด์

การกำหนดค่านี้เปลี่ยนเซิร์ฟเวอร์ Qdrant MCP ให้เป็นเครื่องมือค้นหาโค้ดเฉพาะทางที่สามารถ:

จัดเก็บส่วนย่อยของโค้ด เอกสารประกอบ และรายละเอียดการนำไปใช้
เรียกคืนตัวอย่างโค้ดที่เกี่ยวข้องตามการค้นหาเชิงความหมาย
ช่วยนักพัฒนาค้นหาการนำไปใช้หรือรูปแบบการใช้งานเฉพาะ

คุณสามารถเติมข้อมูลในฐานข้อมูลโดยจัดเก็บคำอธิบายภาษาธรรมชาติของส่วนย่อยโค้ด (ในพารามิเตอร์ information) พร้อมกับโค้ดจริง (ในคุณสมบัติ metadata.code) จากนั้นค้นหาโดยใช้คำค้นหาภาษาธรรมชาติ ที่อธิบายสิ่งที่คุณกำลังมองหา

[!NOTE] คำอธิบายเครื่องมือที่ให้ไว้ข้างต้นเป็นตัวอย่างและอาจต้องปรับแต่งสำหรับกรณีการใช้งานเฉพาะของคุณ พิจารณา ปรับคำอธิบายให้ตรงกับเวิร์กโฟลว์ของทีมและประเภทเฉพาะของส่วนย่อยโค้ดที่คุณต้องการ จัดเก็บและเรียกคืนมากขึ้น

หากคุณติดตั้ง mcp-server-qdrant สำเร็จแล้ว แต่ยังไม่สามารถทำให้มันทำงานกับ Cursor ได้ โปรด พิจารณาสร้าง กฎ Cursor เพื่อให้เครื่องมือ MCP ถูกใช้เสมอเมื่อ เอเจนต์สร้างส่วนย่อยโค้ดใหม่ คุณสามารถจำกัดกฎให้ทำงานเฉพาะกับประเภทไฟล์บางประเภท เพื่อหลีกเลี่ยงการใช้ เซิร์ฟเวอร์ MCP สำหรับเอกสารประกอบหรือเนื้อหาประเภทอื่นๆ

การใช้กับ Claude Code

คุณสามารถเพิ่มขีดความสามารถของ Claude Code ได้โดยการเชื่อมต่อกับเซิร์ฟเวอร์ MCP นี้ ทำให้สามารถค้นหาเชิงความหมายเหนือ ฐานโค้ดที่มีอยู่ของคุณ

การตั้งค่า mcp-server-qdrant

เพิ่มเซิร์ฟเวอร์ MCP ไปยัง Claude Code:

# Add mcp-server-qdrant configured for code search
claude mcp add code-search \
-e QDRANT_URL="http://localhost:6333" \
-e COLLECTION_NAME="code-repository" \
-e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
-e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \
-e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \
-- uvx mcp-server-qdrant

ตรวจสอบว่าได้เพิ่มเซิร์ฟเวอร์แล้ว:
```
claude mcp list
```

การใช้การค้นหาโค้ดเชิงความหมายใน Claude Code

คำอธิบายเครื่องมือ ที่ระบุใน TOOL_STORE_DESCRIPTION และ TOOL_FIND_DESCRIPTION แนะนำ Claude Code เกี่ยวกับวิธีการใช้ เซิร์ฟเวอร์ MCP ตัวอย่างที่ให้ไว้ข้างต้นเป็นตัวอย่างและอาจต้องปรับแต่งสำหรับกรณีการใช้งานเฉพาะของคุณ อย่างไรก็ตาม Claude Code ควรจะสามารถ:

ใช้เครื่องมือ qdrant-store เพื่อจัดเก็บส่วนย่อยโค้ดพร้อมคำอธิบาย
ใช้เครื่องมือ qdrant-find เพื่อค้นหาส่วนย่อยโค้ดที่เกี่ยวข้องโดยใช้ภาษาธรรมชาติ

รันเซิร์ฟเวอร์ MCP ในโหมดการพัฒนา

เซิร์ฟเวอร์ MCP สามารถรันในโหมดการพัฒนาได้โดยใช้คำสั่ง mcp dev นี่จะเริ่มเซิร์ฟเวอร์และเปิด MCP inspector ในเบราว์เซอร์ของคุณ

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

การใช้กับ VS Code

สำหรับการติดตั้งในคลิกเดียว คลิกปุ่มติดตั้งด้านล่าง:

การติดตั้งด้วยตนเอง

เพิ่มบล็อก JSON ต่อไปนี้ในไฟล์การตั้งค่าผู้ใช้ (JSON) ของคุณใน VS Code คุณสามารถทำได้โดยกด Ctrl + Shift + P และพิมพ์ Preferences: Open User Settings (JSON)

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "uvx",
        "args": ["mcp-server-qdrant"],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

หรือหากคุณต้องการใช้ Docker ให้เพิ่มการกำหนดค่านี้แทน:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "docker",
        "args": [
          "run",
          "-p", "8000:8000",
          "-i",
          "--rm",
          "-e", "QDRANT_URL",
          "-e", "QDRANT_API_KEY",
          "-e", "COLLECTION_NAME",
          "mcp-server-qdrant"
        ],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

อีกทางหนึ่ง คุณสามารถสร้างไฟล์ .vscode/mcp.json ในพื้นที่ทำงานของคุณด้วยเนื้อหาต่อไปนี้:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

สำหรับการกำหนดค่าพื้นที่ทำงานด้วย Docker ใช้สิ่งนี้ใน .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "docker",
      "args": [
        "run",
        "-p", "8000:8000",
        "-i",
        "--rm",
        "-e", "QDRANT_URL",
        "-e", "QDRANT_API_KEY",
        "-e", "COLLECTION_NAME",
        "mcp-server-qdrant"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

การมีส่วนร่วม

หากคุณมีข้อเสนอแนะเกี่ยวกับวิธีการปรับปรุง mcp-server-qdrant หรือต้องการรายงานข้อบกพร่อง เปิด issue ได้เลย! เรายินดีรับทุกการมีส่วนร่วม

การทดสอบ `mcp-server-qdrant` ภายในเครื่อง

MCP inspector เป็นเครื่องมือสำหรับนักพัฒนาสำหรับการทดสอบและดีบักเซิร์ฟเวอร์ MCP มันรันทั้ง UI ไคลเอนต์ (พอร์ตเริ่มต้น 5173) และพร็อกซีเซิร์ฟเวอร์ MCP (พอร์ตเริ่มต้น 3000) เปิด UI ไคลเอนต์ใน เบราว์เซอร์ของคุณเพื่อใช้ inspector

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

เมื่อเริ่มต้นแล้ว เปิดเบราว์เซอร์ของคุณไปที่ http://localhost:5173 เพื่อเข้าถึงอินเทอร์เฟซ inspector

ใบอนุญาต

เซิร์ฟเวอร์ MCP นี้ได้รับอนุญาตภายใต้ Apache License 2.0 ซึ่งหมายความว่าคุณมีอิสระในการใช้ แก้ไข และแจกจ่ายซอฟต์แวร์ ภายใต้ข้อกำหนดและเงื่อนไขของ Apache License 2.0 สำหรับรายละเอียดเพิ่มเติม โปรดดูไฟล์ LICENSE ในที่เก็บของโปรเจกต์