tuma250-mcp 0.1.4

MCP server for the Tuma250 grocery site (Kigali, Rwanda)

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.

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=[e-mail]
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": "[e-mail]",
        "TUMA250_PASSWORD": "your-password"
      }
    }
  }
}

Direct (stdio)

pip install tuma250-mcp
TUMA250_USERNAME=[e-mail] 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. Use get_product_variations to discover the available options first:

1. search_products("fresh carrots")          → returns product URL
2. get_product_variations(product_url)       → lists 250g / 500g / 1kg variants
3. add_to_cart(product_id, variation_id, variation_attributes)

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.

License

MIT