# RappiMCP

<!-- mcp-name: io.github.bgirardi99/rappi-mcp -->

```
Program : RappiMCP
Author  : Bastian Girardi
Date    : April 2, 2026
Purpose : Built to automate grocery and delivery purchases on Rappi Chile
          through Claude — eliminating the need to manually browse the app
          when you just want to tell an AI what you need and have it ordered.
```

---

An MCP (Model Context Protocol) server that gives Claude full control over Rappi Chile — browse stores, search products, manage the cart, and open checkout — all through natural language.

## How it works

The server is built with [FastMCP](https://github.com/jlowin/fastmcp) and exposes tools that Claude can call. It communicates with Rappi via their internal web API (`services.rappi.cl`), authenticated with tokens extracted directly from a Chrome browser session using the Chrome DevTools Protocol (CDP).

```
Claude ──tools──▶ rappi_mcp.py ──HTTP──▶ services.rappi.cl
                       │
                       └──CDP──▶ Chrome (auth + checkout navigation)
```

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure Claude Code

Add this to your Claude Code MCP settings (`claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "RappiMCP": {
      "command": "python",
      "args": ["C:/path/to/RappiMCP/rappi_mcp.py"]
    }
  }
}
```

### 3. Authenticate

On first use, call `rappi_auth` to extract your Rappi credentials from Chrome and save them to `.env`. No manual token copying needed.

## Authentication

Rappi uses rotating JWT tokens stored as browser cookies. The auth flow:

1. **`rappi_auth(use_existing_chrome=False)`** — launches a dedicated Chrome window at rappi.cl (on CDP port `9223`) and waits up to 2 minutes for you to log in
2. Once logged in, it reads three cookies via CDP:
   - `rappi.data` (Base64 JSON) → `user_id`
   - `deviceid` → `device_id`
   - `rappi_refresh_token` → `refresh_token`
3. Exchanges the refresh token for a fresh `access_token` via `POST /api/rocket/refresh-token`
4. Writes all four values to `.env`

**`rappi_auth(use_existing_chrome=True)`** (default) — attaches to an already-running Chrome with `--remote-debugging-port=9223` and reads cookies immediately (you must already be logged in).

### Token refresh

`RappiClient` handles token rotation automatically. If any API response includes the header `x-refresh-token: true`, it transparently refreshes both tokens and retries the request.

### Environment variables

```
RAPPI_ACCESS_TOKEN   — Bearer token for API calls
RAPPI_REFRESH_TOKEN  — Used to obtain new access tokens
RAPPI_DEVICE_ID      — UUID identifying the browser session
RAPPI_USER_ID        — Numeric Rappi user ID
```

See `.env.example` for the expected format.

## Tools reference

### `rappi_auth(use_existing_chrome=True)`
Extract credentials from Chrome and write them to `.env`. Set `use_existing_chrome=False` to launch a fresh Chrome window and wait for login.

---

### `rappi_reload()`
Reload tokens from `.env` and restart the API client — without restarting the MCP server. Useful after manually editing `.env`.

---

### `rappi_list_stores(category, query, limit)`
List stores available for delivery near your saved address.

| Param | Default | Description |
|-------|---------|-------------|
| `category` | `"market"` | Store category: `"market"`, `"restaurant"`, `"farma"`, `"licores"`, `"express-big"`, or any Rappi store_type slug |
| `query` | `""` | Optional name filter |
| `limit` | `50` | Max results |

Returns: `store_id`, `name`, `store_type`, `lat`, `lng`, `eta`, `shipping_cost`.

> `store_id` is used by `rappi_search_products`. `store_type` is used by all cart tools.

---

### `rappi_get_store(store_id)`
Look up metadata for a specific store by its numeric ID. Returns `store_type` (the slug needed for cart operations).

---

### `rappi_search_products(store_id, query, size, offset)`
Search products within a store. Queries in Spanish work best.

| Param | Default | Description |
|-------|---------|-------------|
| `store_id` | required | From `rappi_list_stores` |
| `query` | required | Search term (e.g. `"cerveza"`, `"preservativos"`) |
| `size` | `40` | Results per page (max 40) |
| `offset` | `0` | Pagination offset |

Returns: `composite_id`, `name`, `trademark`, `price`, `real_price`, `discount`, `quantity`, `unit_type`, `sale_type`, `in_stock`.

> Use `composite_id` and `sale_type` when adding to cart.

---

### `rappi_get_cart(store_type)`
Read the current cart contents for a given store. Returns a list of items with `composite_id`, `units`, `sale_type`, `name`, `price`.

---

### `rappi_add_to_cart(store_id, store_type, composite_id, units, sale_type)`
Add a product to the cart (or increment its quantity if already present). Internally: reads current cart → appends/increments → writes back via a full PUT.

---

### `rappi_remove_from_cart(store_id, store_type, composite_id)`
Remove a specific product from the cart by its `composite_id`.

---

### `rappi_clear_cart(store_id, store_type)`
Empty the entire cart for a store.

---

### `rappi_checkout(store_type)`
Navigate Chrome to the checkout page for a store. Each store has its own checkout URL:

```
https://www.rappi.cl/checkout/{store_type}
```

Examples:
- `turbo_rappidrinks_nc` → `rappi.cl/checkout/turbo_rappidrinks_nc`
- `cruz_verde_rappido_nc` → `rappi.cl/checkout/cruz_verde_rappido_nc`
- `lider` → `rappi.cl/checkout/lider`

> Rappi does not support consolidated multi-store checkout. Each store cart must be checked out separately.

## Typical flow

```
1. rappi_auth()                          # authenticate once
2. rappi_list_stores(category="farma")   # find pharmacies
3. rappi_search_products(store_id, "preservativos")  # search
4. rappi_add_to_cart(store_id, store_type, composite_id, 1, "U")
5. rappi_checkout(store_type)            # open checkout in Chrome
```

## File structure

```
RappiMCP/
├── rappi_mcp.py      # MCP server — tool definitions, auth logic, CDP helpers
├── rappi_client.py   # Rappi API client with automatic token refresh
├── requirements.txt  # Python dependencies
├── .env              # Credentials (git-ignored)
└── .env.example      # Credentials template
```

## Notes

- The server uses CDP port `9223` (not the default `9222`) to avoid conflicts with other tools
- Checkout navigation also uses CDP — the same Chrome instance used for auth
- `store_type` slugs come from `rappi_list_stores` and must be passed exactly as returned (e.g. `"turbo_rappidrinks_nc"`, not `"turbo"`)