Milkbasket Server

npm version npm downloads License: MIT MCP Node.js

AI-powered grocery shopping for India — a Model Context Protocol (MCP) server for the Milkbasket API.

Connect your AI assistant (Cursor, Claude Desktop, Windsurf, or any MCP client) to your Milkbasket account and let it handle your daily groceries — log in with OTP, browse products, build your cart, check your wallet, and review your full order summary, all through natural language.

What you can do with this:

• Ask your AI to find products — "Search for low-fat milk under ₹50"
• Build and manage your cart — "Add 2 Amul butter, remove the lassi"
• Check your order before delivery — "Show me my cart with the full bill"
• Keep track of your wallet — "What's my Milkbasket balance?"
• Fetch account details — "What city and hub am I assigned to?"

Prerequisites

• Node.js 18 or higher
• A Milkbasket account (Indian mobile number)
• An MCP client (Cursor, Claude Desktop, etc.)

Installation

Option 1: npx (recommended, no install needed)

{
  "mcpServers": {
    "milkbasket": {
      "command": "npx",
      "args": ["-y", "@anujsup/milkbasket-mcp@latest"]
    }
  }
}

Option 2: Global install

npm install -g @anujsup/milkbasket-mcp

{
  "mcpServers": {
    "milkbasket": {
      "command": "milkbasket-mcp"
    }
  }
}

Option 3: Local install

npm install @anujsup/milkbasket-mcp

{
  "mcpServers": {
    "milkbasket": {
      "command": "node",
      "args": ["node_modules/@anujsup/milkbasket-mcp/dist/index.js"]
    }
  }
}

Cursor setup

Add the config to .cursor/mcp.json in your project root (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "milkbasket": {
      "command": "npx",
      "args": ["-y", "@anujsup/milkbasket-mcp@latest"]
    }
  }
}

Reload Cursor after saving.

Available Tools

Authentication

Tool	Description
auth_request_otp	Send OTP to your registered mobile number
auth_verify_otp	Verify OTP and log in
auth_status	Check if you are currently authenticated
auth_logout	Log out and clear stored tokens

User

Tool	Description
get_user_details	Fetch your name, email, city, hub, and membership info
get_wallet_balance	Fetch your current Milkbasket wallet balance and cashback

Products

Tool	Description
list_products	List featured/flash-deal products (paginated)
search_products	Search products by name or keyword (paginated)
get_hero_collections	Fetch hero banner collections shown on the home screen

Cart

Tool	Description
add_to_cart	Add a new product or increase quantity in the cart
remove_from_cart	Decrease quantity or remove a product from the cart
get_basket	Lightweight cart snapshot — item count, product IDs, basic totals
get_extended_basket	Full cart view — product names, images, discounts, delivery fee, GST, final payable amount

Authentication Flow

1. auth_request_otp  →  { phone: "9XXXXXXXXX" }
2. Receive OTP via SMS
3. auth_verify_otp   →  { phone: "9XXXXXXXXX", otp: "XXXX" }
4. You are now logged in

Security & Privacy

This server runs 100% locally on your machine. Your phone number, OTP, and tokens never leave your device — they are never sent to any third party, including the AI assistant. Here's exactly what happens:

• Your phone number is sent directly from your machine to Milkbasket's servers to request an OTP
• The OTP you share with the AI is passed directly from your machine to Milkbasket to verify login
• The AI model only sees the response (success/failure) — it cannot intercept or store your credentials
• Access tokens are stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) using keytar — the same secure storage used by apps like VS Code and 1Password
• If keytar is unavailable, an AES-256-GCM encrypted file is used as fallback
• You can log out at any time using auth_logout, which clears all stored tokens immediately

Cart Flow

search_products  →  find productId and price
add_to_cart      →  { productId, price, quantity }
remove_from_cart →  { productId, price, quantity: 0 }  ← set 0 to delete
get_extended_basket  →  full checkout view

What you can ask your AI

Once connected, just talk to your AI naturally:

What you say	What happens
"Log me in to Milkbasket"	Sends OTP → verifies → stores token
"Search for paneer"	Calls search_products and returns matches
"Add 2 Amul Gold milk to my cart"	Calls add_to_cart with the right product
"Remove the lassi from my cart"	Calls remove_from_cart with quantity 0
"Show me my cart with full bill"	Calls get_extended_basket with itemized bill
"What is my wallet balance?"	Calls get_wallet_balance
"What are my account details?"	Calls get_user_details — name, city, hub, membership
"What deals are on today?"	Calls list_products for flash deals
"Log me out"	Clears tokens from keychain

Example usage in Cursor

Search for Amul milk products
→ search_products({ query: "amul milk" })

Add 2 units to cart
→ add_to_cart({ productId: 1234, price: 28, quantity: 2 })

View full cart with bill breakdown (product names, discounts, delivery fee, GST, payable)
→ get_extended_basket()

Reduce quantity by 1
→ remove_from_cart({ productId: 1234, price: 28, quantity: 1 })

Remove product entirely
→ remove_from_cart({ productId: 1234, price: 28, quantity: 0 })

Check wallet balance
→ get_wallet_balance()

Get account info
→ get_user_details()

License

MIT © Anujsup