tuma250-mcp
Allows Perplexity to search products, manage a shopping cart, and browse order history on the Tuma250 grocery site.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tuma250-mcp Search for fresh vegetables"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tuma250-mcp
An MCP server for the Tuma 250 grocery site (Kigali, Rwanda).
Gives any MCP-compatible AI client (Cursor, Claude Desktop, etc.) the ability to search products, manage a shopping cart, and browse order history on Tuma250 — using a headless Playwright browser under the hood.
Example uses
Imported as MCP server in Perplexity (or any other MCP-compatible client)

Imported as a skill in OpenClaw
The skill definition can be copied from skills/tuma250/SKILL.md (requires the mcporter skill to be enabled, and the MCP server added to its configuration)

Related MCP server: hazi-hinam
Tools
Tool | Description |
| Authenticate and persist the browser session |
| Search for products by keyword |
| List available variants (size/weight) for a variable product |
| Add a product (or specific variant) to the cart |
| Retrieve cart contents with full cost breakdown |
| List recent orders from My Account |
| Fetch line items for a specific order |
Prerequisites
Playwright with one headless browser
npm i -g playwright
playwright install chromiumConfiguration
The server reads credentials from environment variables (or a .env file):
TUMA250_BASE_URL=https://tuma250.com
TUMA250_USERNAME=your-email@example.com
TUMA250_PASSWORD=your-password
# Optional
TUMA250_SESSION_FILE=.tuma250_session.json # persists login between runs
TUMA250_DEBUG=false # set true for headed browserUsage
Cursor / Claude Desktop
Add to ~/.cursor/mcp.json / ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"tuma250": {
"command": "uvx",
"args": ["tuma250-mcp"],
"env": {
"TUMA250_BASE_URL": "https://tuma250.com",
"TUMA250_USERNAME": "your-email@example.com",
"TUMA250_PASSWORD": "your-password"
}
}
}
}Direct (stdio)
pip install tuma250-mcp
TUMA250_USERNAME=you@example.com TUMA250_PASSWORD=secret tuma250-mcpSession persistence
After the first successful login, the browser session (cookies) is saved to TUMA250_SESSION_FILE (default: .tuma250_session.json). Subsequent runs reuse the saved session and skip the login step entirely.
Variable products
Some products on Tuma250 require a size/weight selection before they can be added to the cart. Pass the product slug (from search_products or get_order_details) and optionally variation_attributes:
1. search_products("fresh carrots") → returns slug in each result
2. get_product_variations(product_url) → lists 250g / 500g / 1kg variants
3. add_to_cart(product_slug, quantity=1, variation_attributes={"attribute_quantity": "500g"})Development
# Clone and setup
uv venv
source .venv/bin/activate # or: .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"
playwright install chromium
# Run tests
pytest -vCopy config-example.env to .env and fill in your Tuma250 credentials before running tests or the server locally.
To test from command line, you may use mcporter, e.g.:
npx mcporter call --stdio "uv run tuma250-mcp" get_cart
npx mcporter call --stdio "uv run tuma250-mcp" 'tuma250.get_order_details(order_id: "193457")'
npx mcporter call --stdio "uv run tuma250-mcp" 'tuma250.add_to_cart(product_slug: "ripe-mango-fruit-1kg")'
npx mcporter call --stdio "uv run tuma250-mcp" add_to_cart --args '{"product_slug": "viande-hachee-de-bouef-ordinaire-regular-ground-beef", "variation_attributes": {"attribute_weight":"1kg"}}'License
MIT
Available Tools
7 toolsadd_to_cartA
Add a product to the Tuma250 shopping cart.
Uses the product slug (from search_products URL or get_order_details). For variable products, pass variation_attributes so the page pre-selects the variant, e.g. {"attribute_quantity": "500g"}.
Args: product_slug: Product URL slug, e.g. "fresh-carrots-1kg" (from URL or get_order_details items). quantity: Number of units to add (default 1). variation_attributes: For variable products, attribute key/value pairs e.g. {"attribute_quantity": "500g"} (from get_order_details or get_product_variations raw_attributes).
Returns: dict containing: - success (bool): Whether the item was confirmed in the cart. - cart_total_items (int): Total number of line items in the cart. - cart_total_price (float | None): Cart grand total. - line_item_summary (list): Each item with id, slug, variation_attributes, name, qty.
Inputs: product_slug (required), quantity, variation_attributes. Returns: object
get_cartA
Retrieve the current contents of the Tuma250 shopping cart.
Returns: dict containing: - items (list): Each item with product_id, slug, variation_attributes, name, qty, price, subtotal. - total_items (int): Number of distinct line items. - subtotal (float | None): Items cost before shipping. - shipping_options (list): Available shipping methods with label and price. - total (float | None): Grand total including selected shipping.
Inputs: no named parameters. Returns: object
get_order_detailsA
Fetch the line items for a specific Tuma250 order.
Args: order_id: The WooCommerce order ID (from list_recent_orders).
Returns: dict containing: - order_id (str) - items (list): Each item with slug, variation_attributes, name, qty, price, brand, unit_size, category_path.
Inputs: order_id (required). Returns: object
get_product_variationsA
Return the available variants for a variable WooCommerce product.
Call this when search_products returns a product and you need to know which size/weight options exist before adding it to the cart.
Args: product_url: Full product page URL (from search_products result["url"]).
Returns: list of variation objects, each containing: - variation_id (str): Pass this to add_to_cart. - attributes (dict): Human-readable attributes, e.g. {"quantity": "500g"}. - raw_attributes (dict): WooCommerce attribute keys, e.g. {"attribute_quantity": "500g"}. - price (float | None): Price for this variant. - in_stock (bool): Whether this variant is currently available. Returns an empty list for simple (non-variable) products.
Inputs: product_url (required). Returns: result
list_recent_ordersA
List recent orders from the Tuma250 "My Orders" page.
Args: limit: Maximum number of orders to return (default 10).
Returns: list of order summary objects, each containing: - order_id (str | None) - date (str | None) - status (str | None) - total (float | None) - link (str | None): URL to the order detail page.
Inputs: limit. Returns: result
loginA
Ensure an authenticated session with the Tuma250 site.
Logs in using the configured credentials if the current session is not already authenticated. Subsequent tool calls auto-login as needed, so calling this tool explicitly is optional.
Returns: dict: {"success": bool, "message": str}
Inputs: no named parameters. Returns: object
search_productsA
Search for products on the Tuma250 grocery site.
Args: query: Free-text search string, e.g. "butter 500g" or "rice 5kg". max_results: Maximum number of products to return (default 10).
Returns: list of product objects, each containing: - id (str | None): WooCommerce product ID. - name (str | None): Product display name. - brand (str | None): Brand name if available. - package_size (str | None): Package size / unit description. - price (float | None): Unit price. - url (str | None): Product page URL. - category_path (str | None): Category breadcrumb.
Inputs: query (required), max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: authentication, product search, variation retrieval, cart addition, cart viewing, order listing, and order details. No overlap or ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (e.g., search_products, add_to_cart, list_recent_orders). Login is a simple verb but fits naturally.
7 tools is well-scoped for an online grocery server. Each tool covers a necessary operation without redundancy or overwhelming number.
Covers product search, cart operations, and order history. Missing cart editing (remove/update items) and checkout, but the core workflow is supported. Minor gap.
Maintenance
Related MCP Connectors
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
Demo AI-first shop: search products, fill a cart and prepare the order (test payments).
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to browse product catalogs, search products with filters, and initiate checkouts, generating order summaries and checkout URLs.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search the catalog, manage a cart and usual orders, find delivery slots, and handle favorites, shopping lists, past orders, and item remarks through the store's API, with login and payment left to the user on the website.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to shop groceries across Rohlik Group platforms by searching products, managing carts, analyzing purchase history for personalized suggestions, and accessing account, order, delivery, and discount information.-
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to search grocery products, manage shopping carts, and access account, order, delivery, and discount information across multiple European online grocery platforms.MIT