Kapruka MCP

Official8 toolsLive

by kapruka · Python

Free public MCP server for Kapruka.com — Sri Lanka's largest e-commerce platform.

Kapruka MCP Server (com.kapruka/kapruka-mcp)

This free public MCP server exposes Kapruka.com’s REST API as MCP tools for LLMs and third-party MCP clients. The server is implemented as a Python MCP server and is associated with Kapruka.com, described as Sri Lanka’s largest e-commerce platform.

🛠️ Key Features

Python MCP server
Wraps the Kapruka.com REST API
Exposes REST capabilities as MCP tools
Identified tool set count: 8

🚀 Use Cases

Use by LLMs via MCP tool calls
Use by third-party MCP clients integrating with Kapruka.com

⚡ Developer Benefits

Streamable HTTP transport (default port: 8000)
Supports stdio transport for MCP Inspector usage
Environment-based configuration using an API URL and key

⚠️ Limitations

Requires Kapruka API credentials configured in .env (copied from .env.example) and running via cli.py server

Captured live from the server via tools/list.

kapruka_list_categories

List top-level Kapruka product categories by name with browse URLs. Returns category names (usable as the `category` filter on kapruka_search_products) plus the public Kapruka.com URL for each category landing page — useful for shopping agents that want to send users directly to a category to browse. Internal IDs and product counts are not exposed. Results are cached for 30 minutes server-side. Args: params (ListCategoriesInput): - depth (int): Sub-category levels to include, 1 or 2 (default 1) - response_format (str): 'markdown' (default) or 'json' Returns: str: Category tree in the requested format. JSON schema: { "categories": [ { "name": str, "url": str, # kapruka.com category landing page "children": [{"name": str, "url": str, "children": [...]}] } ] } Error: "Error: <message>" on failure.

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/ListCategoriesInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "ListCategoriesInput": {
      "additionalProperties": false,
      "properties": {
        "depth": {
          "default": 1,
          "description": "How many levels of sub-categories to include (1 or 2). Default 1.",
          "maximum": 2,
          "minimum": 1,
          "title": "Depth",
          "type": "integer"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' for human-readable output, 'json' for raw structured data.",
          "title": "Response Format",
          "type": "string"
        }
      },
      "title": "ListCategoriesInput",
      "type": "object"
    }
  },
  "title": "kapruka_list_categoriesArguments"
}

kapruka_get_product

Fetch full details for a single Kapruka product by its product ID. Returns name, description, price (with optional currency conversion), stock status, images, variants, shipping info, delivery scope, and a direct product URL. Delivery scope: most gifts ship island-wide, but restaurant food, hotel cakes and liquor only reach a limited city set (typically the Colombo area). The `delivery` object is the authority — search results do NOT carry it. When `delivery.island_wide` is false, tell the customer up front that the item is delivered only to selected cities, and confirm their city with kapruka_check_delivery(city, product_id) before promising anything. If `deliverable_city_count` exceeds the returned list, the list is truncated — say "and more", don't treat it as complete. Note: Some IDs starting with 'CATSYM' are category landing pages, not purchasable products — this tool will flag those clearly. Args: params (GetProductInput): - product_id (str): Kapruka product ID (e.g. 'cakeXX000000') - currency (str): Price currency — LKR (default), USD, GBP, AUD, CAD, EUR - type (Optional[str]): Optional type hint (e.g. 'specialgifts') - response_format (str): 'markdown' (default) or 'json' Returns: str: Product details in the requested format. JSON schema: { "id": str, "name": str, "description": str, "summary": str, "price": {"amount": float, "currency": str}, "compare_at_price": {"amount": float, "currency": str} | null, "in_stock": bool, "stock_level": str, # "low" | "medium" | "high" "category": {"id": str, "name": str, "slug": str, "path": str}, "variants": [{"id": str, "name": str, "sku": str, "price": {...}, "in_stock": bool, "stock_level": str, "attributes": {...}}], "images": [str], # list of full-resolution image URLs "attributes": {"type": str, "subtype": str, "weight": str, "vendor": str}, "shipping": {"ships_from": str, "ships_internationally": bool, "restricted_countries": [str]}, "delivery": { "island_wide": bool, "deliverable_city_count": int, # only when island_wide=false; TRUE total "deliverable_cities": [str] # only when island_wide=false; capped at 60 }, "rating": null, "url": str } Error: "Error: <message>" on failure.

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/GetProductInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "GetProductInput": {
      "additionalProperties": false,
      "properties": {
        "product_id": {
          "description": "Kapruka product ID (e.g. 'cakeXX000000', 'EF_PC_CHOC0V2774P00065')",
          "maxLength": 80,
          "minLength": 3,
          "title": "Product Id",
          "type": "string"
        },
        "currency": {
          "default": "LKR",
          "description": "Price currency. Supported: LKR, USD, GBP, AUD, CAD, EUR",
          "title": "Currency",
          "type": "string"
        },
        "type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional product type hint passed to the API (e.g. 'specialgifts'). Rarely needed.",
          "title": "Type"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' for human-readable output, 'json' for raw structured data.",
          "title": "Response Format",
          "type": "string"
        }
      },
      "required": [
        "product_id"
      ],
      "title": "GetProductInput",
      "type": "object"
    }
  },
  "title": "kapruka_get_productArguments"
}

kapruka_search_products

Search for products on Kapruka.com by keyword, with optional category filter and pagination. Returns a ranked list of matching products with prices, stock status, images, and URLs. Supports cursor-based pagination — pass next_cursor from one response into the next call. Pagination is capped at 3 pages per query to discourage catalog enumeration; for broader discovery, refine the query or filter by category instead. Queries must be at least 3 characters and contain specific terms — pure stopword queries (e.g. "the", "a an") are rejected. By default, category landing pages (CATSYM entries with price=0) are filtered out so results contain only purchasable products. Set include_stubs=true to include them. Search results carry NO delivery-scope information. Food, hotel cakes and liquor are delivered only to selected cities — never infer deliverability from a search hit. Before quoting delivery on a specific item, call kapruka_get_product (read `delivery.island_wide`) or kapruka_check_delivery with `product_id`. Args: params (SearchProductsInput): - q (str): Search query (e.g. 'birthday cake', 'roses', 'tea gift'). Min 3 chars. - category (Optional[str]): Category filter (e.g. 'Birthday', 'Flowers') - limit (int): Results per page, 1–50 (default 10) - cursor (Optional[str]): Pagination cursor from previous response - currency (str): LKR (default), USD, GBP, AUD, CAD, EUR - min_price (Optional[float]): Min price (inclusive) in the requested currency - max_price (Optional[float]): Max price (inclusive) in the requested currency - in_stock_only (bool): Restrict to in-stock items (default false) - sort (str): 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'bestseller' - include_stubs (bool): Include category landing pages (default false) - response_format (str): 'markdown' (default) or 'json' Returns: str: Search results in the requested format. JSON schema: { "results": [ { "id": str, "name": str, "summary": str, "price": {"amount": float | null, "currency": str}, "compare_at_price": {"amount": float, "currency": str} | null, "in_stock": bool, "stock_level": str, "image_url": str | null, "category": {"id": str, "name": str, "slug": str}, "rating": null, "ships_internationally": bool, "url": str } ], "next_cursor": str | null, # null after page 3 even if upstream has more "applied_filters": {"q": str, "limit": int, "in_stock_only": bool} } Error: "Error: <message>" or "No products found for '<query>'" on failure.

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/SearchProductsInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "SearchProductsInput": {
      "additionalProperties": false,
      "properties": {
        "q": {
          "description": "Search query (e.g. 'birthday cake', 'roses', 'chocolates for mom'). Min 3 characters, must contain specific terms (not stopwords only).",
          "maxLength": 200,
          "minLength": 3,
          "title": "Q",
          "type": "string"
        },
        "category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Filter by category name (e.g. 'Birthday', 'Cakes', 'Flowers'). Case-insensitive.",
          "title": "Category"
        },
        "limit": {
          "default": 10,
          "description": "Number of results to return (1–50).",
          "maximum": 50,
          "minimum": 1,
          "title": "Limit",
          "type": "integer"
        },
        "cursor": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Pagination cursor from a previous search response's 'next_cursor' field.",
          "title": "Cursor"
        },
        "currency": {
          "default": "LKR",
          "description": "Price currency. Supported: LKR, USD, GBP, AUD, CAD, EUR",
          "title": "Currency",
          "type": "string"
        },
        "min_price": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Minimum price (inclusive), in the requested currency.",
          "title": "Min Price"
        },
        "max_price": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Maximum price (inclusive), in the requested currency.",
          "title": "Max Price"
        },
        "in_stock_only": {
          "default": false,
          "description": "If true, only return products currently in stock.",
          "title": "In Stock Only",
          "type": "boolean"
        },
        "sort": {
          "default": "relevance",
          "description": "Sort order: 'relevance' (default), 'price_asc', 'price_desc', 'newest', 'bestseller'.",
          "title": "Sort",
          "type": "string"
        },
        "include_stubs": {
          "default": false,
          "description": "If false (default), category landing pages (CATSYM entries, price=0) are filtered out.",
          "title": "Include Stubs",
          "type": "boolean"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' for human-readable output, 'json' for raw structured data.",
          "title": "Response Format",
          "type": "string"
        }
      },
      "required": [
        "q"
      ],
      "title": "SearchProductsInput",
      "type": "object"
    }
  },
  "title": "kapruka_search_productsArguments"
}

kapruka_create_order

Create a guest-checkout order on Kapruka and return a click-to-pay link. Builds a Kapruka order from the supplied cart + recipient + delivery + sender, then returns a checkout URL the customer opens in a browser to complete payment. No Kapruka account is required. Prices are locked for the lifetime of the link (60 minutes) — the customer pays exactly the quoted grand total even if the catalog price changes meanwhile. Free public tier limits: 30 orders per hour per client IP. Cart up to 30 items, quantity up to 99 per item. A fresh idempotency key is generated per call so retries on transient errors return the same checkout URL rather than duplicates. Args: params (CreateOrderInput): - cart (list[CartItem]): 1–30 lines. Catalogue line: product_id, quantity (default 1), optional icing_text (cakes only). Custom cake line: custom_cake_request_id + phone — orders the cake Kapruka staff quoted via kapruka_custom_cake_status (status must be 'quoted'; quantity is always 1; never send a price). Lines can be mixed in one order — one delivery fee covers everything; the whole cart must be deliverable to delivery.city. Only place a custom cake order after the customer clearly accepted the quoted total. - recipient (Recipient): name + phone (E.164 +9477… or local 077…) - delivery (Delivery): address, city (must be Kapruka-deliverable — use kapruka_list_delivery_cities), location_type (house/apartment/office/other, default house), date (YYYY-MM-DD, today-or-future Asia/Colombo), optional instructions - sender (Sender): name + anonymous flag - gift_message (Optional[str]): Up to 300 chars - currency (str): LKR (default), USD, GBP, AUD, CAD, EUR - response_format (str): 'markdown' (default) or 'json' Returns: str: Order confirmation with checkout URL. JSON schema: { "checkout_url": str, # Open in browser to pay (no login required) "order_ref": str, # e.g. "ORD-20260520-7823" "order_id": str, # id used by the bank-deposit flow "summary": { "items_total": number, "delivery_fee": number, "addons_total": number, "grand_total": number, # items_total + delivery_fee + addons_total "currency": str }, "expires_at": str # ISO 8601 — link stops working after this } Error: "Error (<code>): <message>" on failure. Common codes: empty_cart, missing_field, past_delivery_date, product_not_found, product_out_of_stock, city_not_deliverable (city not in the network at all), date_not_deliverable, city_not_deliverable_for_item. Custom cake lines add: request_not_found (404 — wrong id/phone or staff removed it), quote_not_ready (409 — staff haven't priced it; check kapruka_custom_cake_status later), quote_expired (410 — submit a new kapruka_custom_cake_request). summary.items_total may differ from the quoted cake total by a few rupees (USD round-trip) — quote the summary numbers when asking for payment. city_not_deliverable_for_item (HTTP 422): at least one cart item (food / hotel cake / liquor) cannot reach delivery.city. NOTHING is created — the API never places a partial order and neither should you. The error text names every blocking item and lists the cities the whole cart CAN go to. Tell the customer which item blocks the order and offer to (a) change the city to one of those, or (b) remove/replace that item. Never retry with the same city. Avoid this entirely by calling kapruka_check_delivery with `product_id` for each limited item before ordering.

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/CreateOrderInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "CartItem": {
      "additionalProperties": false,
      "description": "One cart line — EITHER a catalogue product OR a quoted custom cake.\n\nCatalogue line:   {\"product_id\": \"...\", \"quantity\": 1, \"icing_text\": \"...\"}\nCustom cake line: {\"custom_cake_request_id\": \"...\", \"phone\": \"+9477...\"}\nThe custom cake line is turned into the staff-quoted cake server-side\n(name, picture, price); quantity is always 1 and no price is ever sent.",
      "properties": {
        "product_id": {
          "anyOf": [
            {
              "maxLength": 80,
              "minLength": 3,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Kapruka product ID (e.g. 'cakeXX000000'). Catalogue line.",
          "title": "Product Id"
        },
        "quantity": {
          "anyOf": [
            {
              "maximum": 99,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Quantity (1–99, default 1). Catalogue lines only.",
          "title": "Quantity"
        },
        "icing_text": {
          "anyOf": [
            {
              "maxLength": 120,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Cake icing text. Silently ignored for non-cake products. Catalogue lines only.",
          "title": "Icing Text"
        },
        "custom_cake_request_id": {
          "anyOf": [
            {
              "maxLength": 80,
              "minLength": 6,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "request_id of a custom cake that kapruka_custom_cake_status reports as 'quoted'. Orders the staff-quoted cake (quantity 1). Requires `phone`.",
          "title": "Custom Cake Request Id"
        },
        "phone": {
          "anyOf": [
            {
              "maxLength": 30,
              "minLength": 7,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The customer.phone the custom cake request was made with (custom cake lines only).",
          "title": "Phone"
        }
      },
      "title": "CartItem",
      "type": "object"
    },
    "CreateOrderInput": {
      "additionalProperties": false,
      "properties": {
        "cart": {
          "description": "1–30 items.",
          "items": {
            "$ref": "#/$defs/CartItem"
          },
          "maxItems": 30,
          "minItems": 1,
          "title": "Cart",
          "type": "array"
        },
        "recipient": {
          "$ref": "#/$defs/Recipient"
        },
        "delivery": {
          "$ref": "#/$defs/Delivery"
        },
        "sender": {
          "$ref": "#/$defs/Sender"
        },
        "gift_message": {
          "anyOf": [
            {
              "maxLength": 300,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional gift card message.",
          "title": "Gift Message"
        },
        "currency": {
          "default": "LKR",
          "description": "Pricing currency. Supported: LKR, USD, GBP, AUD, CAD, EUR.",
          "title": "Currency",
          "type": "string"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' (default) or 'json'.",
          "title": "Response Format",
          "type": "string"
        }
      },
      "required": [
        "cart",
        "recipient",
        "delivery",
        "sender"
      ],
      "title": "CreateOrderInput",
      "type": "object"
    },
    "Delivery": {
      "additionalProperties": false,
      "properties": {
        "address": {
          "description": "Street address.",
          "maxLength": 250,
          "minLength": 3,
          "title": "Address",
          "type": "string"
        },
        "city": {
          "description": "Must be a Kapruka delivery city (canonical name from kapruka_list_delivery_cities) that EVERY cart item can reach. The order ships as one shipment, so food / hotel cake / liquor items restrict the whole cart to their city set — verify with kapruka_check_delivery(city, product_id) first; otherwise the order is rejected with city_not_deliverable_for_item.",
          "maxLength": 100,
          "minLength": 2,
          "title": "City",
          "type": "string"
        },
        "location_type": {
          "default": "house",
          "description": "One of: house, apartment, office, other.",
          "title": "Location Type",
          "type": "string"
        },
        "date": {
          "description": "Delivery date in YYYY-MM-DD (Asia/Colombo). Must be today or future.",
          "title": "Date",
          "type": "string"
        },
        "instructions": {
          "anyOf": [
            {
              "maxLength": 250,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Free-form delivery instructions.",
          "title": "Instructions"
        }
      },
      "required": [
        "address",
        "city",
        "date"
      ],
      "title": "Delivery",
      "type": "object"
    },
    "Recipient": {
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "Recipient name shown on the order.",
          "maxLength": 80,
          "minLength": 1,
          "title": "Name",
          "type": "string"
        },
        "phone": {
          "description": "Recipient phone — E.164 (+9477…) or local SL (077…) format.",
          "maxLength": 30,
          "minLength": 7,
          "title": "Phone",
          "type": "string"
        }
      },
      "required": [
        "name",
        "phone"
      ],
      "title": "Recipient",
      "type": "object"
    },
    "Sender": {
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "Sender name on the gift card.",
          "maxLength": 80,
          "minLength": 1,
          "title": "Name",
          "type": "string"
        },
        "anonymous": {
          "default": false,
          "description": "If true, gift card shows 'Anonymous' instead of the sender name.",
          "title": "Anonymous",
          "type": "boolean"
        }
      },
      "required": [
        "name"
      ],
      "title": "Sender",
      "type": "object"
    }
  },
  "title": "kapruka_create_orderArguments"
}

kapruka_track_order

Look up status and delivery progress for a Kapruka order by order number. Returns current status (received / confirmed / out-for-delivery / delivered / cancelled), the recipient and delivery details on file, a timestamped progress timeline, the cart contents, and flags for whether a delivery photo or video is available. Use this after a customer has placed and paid for an order and reads back the order number from their confirmation email or the order complete page. The order number is NOT the `order_ref` returned by kapruka_create_order (which is the pre-payment checkout reference). Once the customer completes payment in the browser, Kapruka emails them a separate order number — that is what this tool expects. Args: params (TrackOrderInput): - order_number (str): Kapruka order number (e.g. 'VIMP34456CB2') - response_format (str): 'markdown' (default) or 'json' Returns: str: Order tracking details in the requested format. JSON schema: { "order_number": str, "pnref": str, # internal payment reference (numeric; not the same as order_number) "status": str, # received | confirmed | shipped | delivered | cancelled | ... "status_display": str, # human label "order_date": str, # human-formatted, Asia/Colombo "delivery_date": str, # human-formatted "shipped_date": str | null, "amount": str, # LKR string (e.g. "15500.00") "payment_method": str, "comments": str | null, "recipient": {"name": str, "phone": str, "address": str, "city": str}, "greeting_message": str | null, "special_instructions": str | null, "progress": [{"step": str, "timestamp": str}], "live_tracking_available": bool, "has_delivery_video": bool, "has_delivery_photo": bool, "items": [{"product_id": str, "name": str, "quantity": int, "selling_price": float}] } Error: "Error: <message>" on failure (e.g. order not found).

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/TrackOrderInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "TrackOrderInput": {
      "additionalProperties": false,
      "properties": {
        "order_number": {
          "description": "Order number from the customer's Kapruka order confirmation email or the order complete page on kapruka.com (e.g. 'VIMP34456CB2'). This is NOT the same as the order_ref returned by kapruka_create_order — the customer must complete payment first; the Kapruka order number is then emailed to them.",
          "maxLength": 40,
          "minLength": 4,
          "title": "Order Number",
          "type": "string"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' (default) or 'json'.",
          "title": "Response Format",
          "type": "string"
        }
      },
      "required": [
        "order_number"
      ],
      "title": "TrackOrderInput",
      "type": "object"
    }
  },
  "title": "kapruka_track_orderArguments"
}

kapruka_render_options_card

Render 1-4 products as ONE shareable JPEG "menu" card and return its URL. The card shows each product's photo with a big numbered badge (the ref you assign), and its name + price printed under the photo. Built for chat commerce (WhatsApp): send the image, tell the customer "reply 1, 2 or 3", and they pick without opening links. No AI is involved — the image is server-composited from the live catalog data, so prices match what the product tools return. Ref numbering contract: refs are yours to assign — use sequential numbers per conversation and NEVER reuse one (if the first card was 1-3, the next card starts at 4). A number must keep meaning the same product for the whole conversation. Args: params (RenderOptionsCardInput): - items (list[CardProduct]): 1-4 of {product_id, ref} - currency (str): LKR (default), USD, GBP, AUD, CAD, EUR - courtesy ({currency, per_usd}, optional): home-currency figure printed under each USD price ("≈ JPY 2,544"); the caller's rate, echoed back - footer_note (str, optional): appended to the footer reply hint Returns: str: JSON: { "card_url": str, # public JPEG URL — send this as the image "items": [{"ref": int, "product_id": str, "name": str, "price": {"amount": float, "currency": str}, "price_note": str | null, "url": str}], "courtesy": {"currency": str, "per_usd": float} | null, # what was printed, or null "unavailable": [str] # product_ids that failed to load (omitted from card) } Error: "Error: <message>" when no product could be loaded.

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/RenderOptionsCardInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "CardProduct": {
      "additionalProperties": false,
      "properties": {
        "product_id": {
          "description": "Kapruka product ID (from a search result).",
          "maxLength": 80,
          "minLength": 3,
          "title": "Product Id",
          "type": "string"
        },
        "ref": {
          "description": "The reference number to print on this product's badge (customer replies with it). Assign sequentially per conversation and NEVER reuse a number.",
          "maximum": 99,
          "minimum": 1,
          "title": "Ref",
          "type": "integer"
        }
      },
      "required": [
        "product_id",
        "ref"
      ],
      "title": "CardProduct",
      "type": "object"
    },
    "Courtesy": {
      "additionalProperties": false,
      "description": "A home-currency approximation to print under each USD price.\n\nThe CALLER supplies the rate it used for its own chat text, so the card and\nthe text agree to the unit; the card never converts on its own. Only\napplied when the card is priced in USD — the courtesy figure describes\nwhat a USD charge will look like on the customer's statement.",
      "properties": {
        "currency": {
          "description": "ISO-4217 code of the customer's home currency, e.g. JPY.",
          "maxLength": 3,
          "minLength": 3,
          "pattern": "^[A-Za-z]{3}$",
          "title": "Currency",
          "type": "string"
        },
        "per_usd": {
          "description": "Units of that currency per 1 USD, as used for the chat text.",
          "exclusiveMaximum": 1000000,
          "exclusiveMinimum": 0,
          "title": "Per Usd",
          "type": "number"
        }
      },
      "required": [
        "currency",
        "per_usd"
      ],
      "title": "Courtesy",
      "type": "object"
    },
    "RenderOptionsCardInput": {
      "additionalProperties": false,
      "properties": {
        "items": {
          "description": "1-4 products to show side by side.",
          "items": {
            "$ref": "#/$defs/CardProduct"
          },
          "maxItems": 4,
          "minItems": 1,
          "title": "Items",
          "type": "array"
        },
        "currency": {
          "default": "LKR",
          "description": "Price currency: LKR, USD, GBP, AUD, CAD, EUR.",
          "title": "Currency",
          "type": "string"
        },
        "courtesy": {
          "anyOf": [
            {
              "$ref": "#/$defs/Courtesy"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional: print '≈ <home currency>' under each USD price (see Courtesy). Ignored unless currency is USD."
        },
        "footer_note": {
          "anyOf": [
            {
              "maxLength": 60,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional short note appended to the footer's reply hint, e.g. 'Checkout charges USD'.",
          "title": "Footer Note"
        }
      },
      "required": [
        "items"
      ],
      "title": "RenderOptionsCardInput",
      "type": "object"
    }
  },
  "title": "kapruka_render_options_cardArguments"
}

kapruka_list_delivery_cities

List or search Sri Lankan cities Kapruka delivers to. Use the `query` param to filter (e.g. "colombo" → all Colombo zones, "anur" → Anuradhapura). Without a query you get the first 25 cities alphabetically, which is rarely what an agent needs — pass a query. Returns canonical city names (use these as the `city` argument to kapruka_check_delivery) plus any common aliases / vernacular spellings. Args: params (ListDeliveryCitiesInput): - query (Optional[str]): Partial match filter - limit (int): Max results, 1–50 (default 25) - response_format (str): 'markdown' (default) or 'json' Returns: str: Cities list in the requested format. JSON schema: { "cities": [{"name": str, "aliases": [str]}], "total_matched": int, "showing": int }

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/ListDeliveryCitiesInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "ListDeliveryCitiesInput": {
      "additionalProperties": false,
      "properties": {
        "query": {
          "anyOf": [
            {
              "maxLength": 50,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Filter cities by partial match against name or aliases (case-insensitive). Omit to see the first `limit` cities alphabetically.",
          "title": "Query"
        },
        "limit": {
          "default": 25,
          "description": "Max cities to return (1–50).",
          "maximum": 50,
          "minimum": 1,
          "title": "Limit",
          "type": "integer"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' (default) or 'json'",
          "title": "Response Format",
          "type": "string"
        }
      },
      "title": "ListDeliveryCitiesInput",
      "type": "object"
    }
  },
  "title": "kapruka_list_delivery_citiesArguments"
}

kapruka_check_delivery

Check whether Kapruka can deliver to a given city on a given date, and at what rate. Returns the flat delivery rate (LKR), whether the requested date is available, and — if not — the next available date plus reason. Kapruka delivers as a single shipment per order at one flat rate regardless of item count. Pass `product_id` whenever the customer has named a product: the answer then also checks that ITEM's delivery scope (restaurant food, hotel cakes and liquor only reach selected cities, typically the Colombo area). With a product_id, `available` is true only if the date is open AND the item is deliverable to that city. When `item_deliverable` is false, offer the customer one of the returned `deliverable_cities` or an island-wide alternative — do not attempt kapruka_create_order with the same city, it will be rejected. An unknown product_id is silently ignored (no item fields in the result), so check `item_deliverable` is present before relying on it. Perishable codes (CAKE*, FLOWER*, COMBO*) additionally get a freshness warning when the chosen delivery date is more than 1 day out. Args: params (CheckDeliveryInput): - city (str): Canonical city name (e.g. 'Colombo 03', 'Galle') - delivery_date (Optional[str]): YYYY-MM-DD; defaults to today (LK time) - product_id (Optional[str]): Check the city against this item's delivery scope - response_format (str): 'markdown' (default) or 'json' Returns: str: Delivery feasibility + rate in the requested format. JSON schema: { "city": str, "now": str, # ISO timestamp, Sri Lanka time "checked_date": str, # YYYY-MM-DD "available": bool, # date open AND (if product_id) item deliverable "rate": number, # flat LKR rate per order "currency": "LKR", "reason": str | null, # date-block message, else "This item is not delivered to <City>." "next_available_date": str|null, # only for date blocks "item_deliverable": bool, # only when product_id resolved to a real product "deliverable_cities": [str], # only when item_deliverable=false (capped at 60) "perishable_warning": str | null # populated when product_id is perishable }

Parameters1

params

any

required

Raw schema

{
  "type": "object",
  "properties": {
    "params": {
      "$ref": "#/$defs/CheckDeliveryInput"
    }
  },
  "required": [
    "params"
  ],
  "$defs": {
    "CheckDeliveryInput": {
      "additionalProperties": false,
      "properties": {
        "city": {
          "description": "Canonical city name (use kapruka_list_delivery_cities to find one). Examples: 'Colombo 03', 'Anuradhapura', 'Galle'.",
          "maxLength": 100,
          "minLength": 2,
          "title": "City",
          "type": "string"
        },
        "delivery_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Target delivery date in ISO format (YYYY-MM-DD), Sri Lanka time. Omit to check today.",
          "title": "Delivery Date"
        },
        "product_id": {
          "anyOf": [
            {
              "maxLength": 80,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Product ID to check the city AGAINST THAT ITEM'S delivery scope. Food, hotel cakes and liquor only reach selected cities — always pass this when a customer names a product and a city, and only promise delivery if `available` is true. Also adds a freshness warning for perishable codes (cake/flower/combo) when the date is >1 day out.",
          "title": "Product Id"
        },
        "response_format": {
          "default": "markdown",
          "description": "'markdown' (default) or 'json'",
          "title": "Response Format",
          "type": "string"
        }
      },
      "required": [
        "city"
      ],
      "title": "CheckDeliveryInput",
      "type": "object"
    }
  },
  "title": "kapruka_check_deliveryArguments"
}

README.md1 KBView on GitHub

Kapruka MCP Server

Python MCP server that wraps the Kapruka.com REST API and exposes it as tools for LLMs and third-party MCP clients.

Setup

bash

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -e ".[dev]"

# 3. Configure environment
cp .env.example .env
# Edit .env with your Kapruka API URL and key

Running

bash

# Start the MCP server (streamable HTTP, default port 8000)
python cli.py server

# Start with stdio transport (for use with MCP Inspector)
python cli.py server --stdio

# Health-check the Kapruka REST API
python cli.py ping

# List registered MCP tools
python cli.py tools

Testing with MCP Inspector

bash

npx @modelcontextprotocol/inspector python cli.py server --stdio

Project Structure

code

src/
  server.py        # FastMCP server entry point
  tools/           # One module per tool group (products, orders, …)
  api/
    client.py      # Async httpx client + error handling
  config/
    settings.py    # Env-based configuration
tests/             # pytest test suite
cli.py             # Developer CLI

Running Tests

bash

pytest

Install

Tools (8)

kapruka_list_categorieskapruka_get_productkapruka_search_productskapruka_create_orderkapruka_track_orderkapruka_render_options_cardkapruka_list_delivery_citieskapruka_check_delivery

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.kapruka.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "kapruka-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.kapruka.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Kapruka MCP Server (com.kapruka/kapruka-mcp)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

kapruka_list_categories

kapruka_get_product

kapruka_search_products

kapruka_create_order

kapruka_track_order

kapruka_render_options_card

kapruka_list_delivery_cities

kapruka_check_delivery

Kapruka MCP Server

Setup

Running

Testing with MCP Inspector

Project Structure

Running Tests

Install

Remote endpoint

Related servers