Cocktails RAG MCP Server

MCP tool for cocktail recommendations using RAG (Retrieval-Augmented Generation).

Requirements

• Python 3.11+
• uv package manager - https://docs.astral.sh/uv/getting-started/installation/

Quick Start

1. Get Groq API key (free): https://console.groq.com/keys

2. Setup:

   # Clone the repository
   git clone https://github.com/00200200/cocktails-rag-mcp.git
   cd cocktails-rag-mcp
   
   # Copy environment template
   cp .env.example .env
   
   # Edit .env and add your GROQ_API_KEY
   nano .env
   
   # Install dependencies
   uv sync
   

3. Pre-download models (required):

   Download embeddings and reranker models:

   uv run python -c "from src.rag.rag import RAG; RAG(); print('Models downloaed!')"
   

4. Install for Claude Desktop:

   Automatic (Recommended)

   uv run fastmcp install claude-desktop fastmcp.json --name cocktails --env-file .env
   

   Manual

   Edit config file:

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

   {
   	"mcpServers": {
   		"cocktails": {
   			"command": "uv",
   			"args": [
   				"run",
   				"--with","faiss-cpu",
   				"--with","fastmcp",
   				"--with","jq",
   				"--with","langchain",
   				"--with","langchain-community",
   				"--with","langchain-groq",
   				"--with","langchain-huggingface",
   				"--with","pandas",
   				"--with","python-dotenv",
   				"--with","sentence-transformers",
   				"fastmcp",
   				"run",
   				"/ABSOLUTE/PATH/TO/src/mcp/server.py:mcp"
   			],
   			"env": {
   				"GROQ_API_KEY": "your_groq_api_key_here"
   			}
   		}
   	}
   }
   

   Replace /ABSOLUTE/PATH/TO/ with your project path and GROQ_API_KEY with your API key.

Example Usage

<p align="center"> <img src="assets/claude_example_1.png" width="600"> </p>

<p align="center"> <img src="assets/claude_example_2.png" width="600"> </p>

Local Testing

# Test RAG pipeline directly
uv run python -m src.rag.rag

# Test MCP server locally
uv run python src/mcp/server.py

Development

Code Formatting

# Format code with black
uv tool run black .

# Sort imports with isort
uv tool run isort .

Project Structure

RAG/
├── src/
│   ├── mcp/         # MCP server implementation (FastMCP)
│   ├── rag/         # RAG pipeline (retrieve, rerank, generate)
│   ├── db/          # FAISS vector database handler
│   └── data/        # Data loading utilities
├── data/            # Cocktail dataset
├── faiss_index/     # Generated FAISS index (auto-created on first run)
├── notebooks/       # EDA notebook
├── fastmcp.json     # FastMCP configuration
├── pyproject.toml   # Project dependencies
└── .env.example     # Environment template

Tech Stack

• MCP Framework: FastMCP
• RAG Framework: LangChain
• Embeddings: BAAI/bge-m3 (local via HuggingFace)
• Vector DB: FAISS (local)
• Reranker: BAAI/bge-reranker-v2-m3 (local via HuggingFace)
• LLM: Groq API (llama-3.1-8b-instant)
• Package Manager: uv