Skip to main content
Glama

tuma250-mcp

PyPI version

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)

Tuma250 MCP diagram

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)

Tuma250 Skill

Related MCP server: hazi-hinam

Tools

Tool

Description

login

Authenticate and persist the browser session

search_products

Search for products by keyword

get_product_variations

List available variants (size/weight) for a variable product

add_to_cart

Add a product (or specific variant) to the cart

get_cart

Retrieve cart contents with full cost breakdown

list_recent_orders

List recent orders from My Account

get_order_details

Fetch line items for a specific order

Prerequisites

Playwright with one headless browser

npm i -g playwright
playwright install chromium

Configuration

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 browser

Usage

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-mcp

Session 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 -v

Copy 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 tools
add_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

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    7 tools is well-scoped for an online grocery server. Each tool covers a necessary operation without redundancy or overwhelming number.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search grocery products, manage shopping carts, and access account, order, delivery, and discount information across multiple European online grocery platforms.
      MIT