mcp-server-snoonu

[!IMPORTANT] Your credentials never leave your machine. All authentication (OTP login, session cookies) is handled locally via a browser on your device. Session data is stored at ~/.mcp-server-snoonu/session.json on your filesystem only — no tokens or passwords are ever sent to or stored on any remote server.

A Model Context Protocol (MCP) server for shopping on Snoonu — Qatar's delivery platform. Search products, manage your cart, and checkout — all from any MCP-compatible agent.

Quick Start

npx mcp-server-snoonu

Claude Code

claude mcp add snoonu -- npx -y mcp-server-snoonu

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "snoonu": {
      "command": "npx",
      "args": ["-y", "mcp-server-snoonu"]
    }
  }
}

Tools

| Tool | Description | | ---------------------- | -------------------------------------------------------------- | | init_session | Initialize or restore a saved auth session | | login | Start OTP login flow with phone number | | verify_otp | Complete login with the 6-digit OTP code | | logout | Clear the current session | | search_products | Search across merchants (supports deep_search for full catalogs) | | bulk_search | Search multiple products at once in parallel (great for grocery lists) | | search_in_merchant | Search within a specific merchant by menu ID | | get_product_details | Get images, descriptions, and stock info for a product | | browse_categories | List top-level categories (Groceries, Restaurants, etc.) | | get_saved_addresses | List saved delivery addresses | | set_delivery_location| Switch delivery location by address ID | | add_to_cart | Add items to cart (requires login) | | get_cart | View current cart contents | | remove_from_cart | Remove items from cart | | clear_cart | Empty the entire cart | | go_to_checkout | Navigate to checkout |

Architecture

src/
├── mcp/
│   ├── server.ts          # Stdio entry point (local use via npx/bunx)
│   ├── server-http.ts     # HTTP entry point (remote/Docker deployment)
│   ├── create-server.ts   # Shared server factory
│   └── tools/             # Tool definitions (Zod schemas + handlers)
│       ├── session.ts     # init_session, login, verify_otp, logout
│       ├── search.ts      # search_products, bulk_search, search_in_merchant, get_product_details
│       ├── cart.ts        # add_to_cart, get_cart, remove_from_cart, clear_cart
│       ├── checkout.ts    # go_to_checkout
│       ├── browse.ts      # browse_categories
│       └── location.ts    # get_saved_addresses, set_delivery_location
├── lib/
│   ├── api-client.ts      # Direct fetch() client for Snoonu APIs
│   ├── session-manager.ts # Cookie/token persistence (~/.mcp-server-snoonu/)
│   └── browser.ts         # Playwright browser for login/checkout flows
└── types/
    └── snoonu/            # TypeScript types for Snoonu API responses

Development

# Clone
git clone https://github.com/Bewinxed/mcp-server-snoonu.git
cd mcp-server-snoonu

# Install
bun install

# Run directly with Bun (no build step)
bun run dev

# Build for npm
bun run build

License

AGPL-3.0 — Copyright (c) 2025 Omar Al Matar

[!NOTE] Disclaimer: This project is not affiliated with, endorsed by, or sponsored by Snoonu or any of its subsidiaries. "Snoonu" is a trademark of Snoonu W.L.L. This is an independent, open-source tool that interacts with publicly available Snoonu web APIs. Use at your own risk and in accordance with Snoonu's terms of service.