Rappi Plugin Claude Openclaw

Order anything from Rappi through conversation. Restaurants, groceries, convenience stores, pharmacies, liquor — if it's on Rappi, you can order it by talking to your AI assistant. The plugin handles searching, browsing, cart management, checkout, and delivery tracking. It learns your preferences over time and gets smarter with every order.

Works on Claude Code, Claude Desktop, Claude Cowork (web), and OpenClaw.

Supports Colombia and Mexico.

Claude Code	OpenClaw

What You Can Do

You: "I'm hungry, order me something from that burger place I liked"

Claude: *checks your order history, finds El Corral*
        *suggests items you've ordered before, scored by taste match*
        *adds to cart with your usual toppings*
        *shows checkout summary with suggested tip*

You: "Looks good, place it"

Claude: *places the order, tracks delivery with real-time ETA*

You: "Find Michelob beer — check Exito and Turbo, whoever has it cheaper"

Claude: *searches both store types, compares prices*
        *Exito: $12,760 for 6-pack | Turbo: $15,480*
        *"Exito has it cheaper — want me to add it to cart?"*

You: "Get me Tylenol from Farmatodo and a bottle of wine from Carulla"

Claude: *searches both stores in parallel*
        *adds Tylenol PM ($32,900) and Casillero del Diablo ($45,000)*
        *shows combined checkout with delivery fees*

The plugin gives your AI assistant 41 tools across all Rappi store types, 4 workflow skills, a specialized ordering agent, and a local memory system that builds a taste profile from your order history.

Store Types

Not just restaurants. The plugin works with every store type on Rappi — cart, checkout, and order tracking automatically detect the correct store type.

Install

Prerequisites

• Python 3.12+
• uv
• A Rappi account (Colombia or Mexico)

Setup

git clone https://github.com/garavitgabriel/rappi-plugin-claude-openclaw.git
cd rappi-plugin-claude-openclaw
uv sync
uv run playwright install chromium

Authenticate

# Colombia (default)
uv run rappi auth login

# Mexico
uv run rappi auth login --country mx

# Headless servers (no browser — SSH, VPS, etc.)
uv run rappi auth token <RAPPI_TOKEN> <DEVICE_ID>
uv run rappi auth token <RAPPI_TOKEN> <DEVICE_ID> --country mx

Your token is saved locally at ~/.rappi/config.json (mode 0600; override the directory with RAPPI_CONFIG_DIR). It never leaves your machine unless you run rappi auth push-railway.

Browser login also captures Rappi's refresh token, so the 7-day access token renews itself automatically — see Auth runbook.

Connect to Your AI Platform

cd rappi-claude-plugin
claude   # MCP server auto-registers from .mcp.json

{
  "mcpServers": {
    "rappi": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/rappi-claude-plugin", "rappi-mcp"]
    }
  }
}

cd rappi-claude-plugin
./install-openclaw.sh       # Handles uv, deps, MCP registration, skills
uv run rappi auth login     # Or: rappi auth token <TOKEN> <DEVICE_ID> (headless)
openclaw gateway restart

uv run rappi build-plugin build --target openclaw --url https://your-server.up.railway.app/sse
openclaw plugins install ~/Desktop/rappi-openclaw-plugin.zip
openclaw gateway restart

Skills

Just talk naturally. The plugin auto-triggers when you mention food, ordering, stores, or Rappi.

Intelligence & Memory

The plugin stores everything locally in SQLite (~/.rappi/rappi.db) and computes a taste profile that gets smarter with every order. All data stays on your machine.

What It Learns

How It Works Without Embeddings (Default)

Everything runs on pure SQL — no external APIs, no cost, no setup:

• "The usual" — Products you've ordered 3+ times from a store
• Time-based suggestions — Stores you order from at this time of day
• New store discovery — Stores matching your preferred type that you haven't tried
• Menu scoring — Ranks items by how often you've ordered them
• Smart search — SQL LIKE matching across all cached products
• Taste profile — Full breakdown of categories, stores, spending, time patterns

How Embeddings Add Semantic Intelligence (Optional)

Enable OpenAI embeddings to unlock meaning-based features on top of the SQL foundation:

export OPENAI_API_KEY="sk-..."
uv run rappi prefs set embeddings.enabled true

How it works: Each product gets a 1536-dimension vector (text-embedding-3-small). Your taste profile is the average of all products you've ordered. Menu scoring = cosine similarity between each item and your taste vector. All vectors stored as BLOBs in SQLite — no external vector database needed.

Cost: ~$0.02 per 1M tokens. A typical menu generates ~100 embeddings. Negligible cost for personal use.

MCP Tools Reference

Terminal (CLI)

uv run rappi go                    # Interactive guided ordering
uv run rappi search "hamburguesa"  # Quick search
uv run rappi store detail 900004   # View a store menu
uv run rappi cart show             # View cart
uv run rappi order checkout        # Place order
uv run rappi history               # Past orders
uv run rappi favorites             # Saved stores
uv run rappi prefs                 # Your preferences

Deployment

The MCP server supports two modes:

• Local (stdio): For Claude Code, Claude Desktop, and OpenClaw — runs as a subprocess
• Remote (SSE over HTTP): For Claude Cowork and OpenClaw — deployed to Railway

Railway Deployment

Deploy on Railway

Or deploy manually:

1. Fork this repo to your GitHub account
2. Connect it to Railway (New Project → Deploy from GitHub)
3. Set environment variables in Railway dashboard:

4. Railway auto-assigns a URL like https://your-app.up.railway.app
5. Verify: curl https://your-app.up.railway.app/health should return ok

Coordinates are auto-synced from your Rappi active address — no need to set lat/lng.

Set the tokens: follow the Auth runbook. rappi auth push-railway sets all three token variables and never prints them.

Auth runbook

How auto-refresh works. Rappi access tokens expire after exactly 7 days. Each login also returns a refresh token, which the plugin saves next to the access token. The client refreshes the token before any request when expiry is less than 48 h away or unknown. It also refreshes when an API call returns 401, then retries that call once. On Railway, a keep-alive task checks every 6 h, so the token renews even when nobody is ordering. The refreshed tokens are written atomically to $RAPPI_CONFIG_DIR/config.json and survive restarts because that directory lives on a volume.

Env seed vs. volume. RAPPI_TOKEN and RAPPI_REFRESH_TOKEN are only seeds. The volume file records a fingerprint of the seed it came from. If the seed is unchanged, the file wins, since it holds the newer refreshed tokens. If push-railway pushed a new seed, the env wins and re-seeds the file. With only the legacy RAPPI_TOKEN set, behavior is unchanged and there is no auto-refresh.

One-time Railway setup (service rappi-claude-plugin):

1. Attach a volume to rappi-claude-plugin mounted at /data.
2. Set RAPPI_CONFIG_DIR=/data/rappi.
3. Locally, in ~/Projects/"Rappi Claude Plugin", run uv run rappi auth login (phone + OTP), then uv run rappi auth push-railway. The second command needs the Railway CLI linked to this project.
4. Confirm that the MCP auth_status tool shows auto_refresh: true and a token_expires_at about 7 days out.

After push-railway, Railway owns the session. If Rappi rotates refresh tokens, the server's first refresh cancels the laptop's copy, so run uv run rappi auth login again locally if you need the CLI.

If RAPPI_REFRESH_TOKEN is set without RAPPI_CONFIG_DIR, the server logs a startup WARNING: refreshed tokens would be lost on every restart, so mount the volume (steps 1–2).

When a tool still says "Token expired…", the refresh itself failed. Re-run step 3 (uv run rappi auth login, then uv run rappi auth push-railway). Locally, uv run rappi auth refresh shows the refresh error code, and uv run rappi auth status shows Expires and Auto-refresh.

What still needs a human: the refresh token eventually expires too. Its lifetime is unknown, likely at least 3 months. Rappi can also revoke it at any time, for example after a password change, a logout on all devices, or a security reset. When that happens, repeat step 3.

Plugin Builds

After deploying to Railway:

# Claude Cowork plugin
uv run rappi build-plugin build --url https://your-app.up.railway.app/sse

# OpenClaw bundle
uv run rappi build-plugin build --target openclaw --url https://your-app.up.railway.app/sse

For Cowork: upload the zip via Cowork > Customize > Plugins, then add the SSE URL as a remote MCP connector. For OpenClaw: openclaw plugins install ~/Desktop/rappi-openclaw-plugin.zip && openclaw gateway restart.

Security

This plugin can place real orders and spend real money. The Rappi auth token grants full access to your account — searching, ordering, and paying. Understand what you're enabling:

• Orders require explicit confirmation — the AI always previews first and asks before placing
• Spending limit — orders over $500,000 COP are blocked by default. Change with rappi prefs set max_order_amount 1000000
• Token storage — access and refresh tokens are saved locally at ~/.rappi/config.json with mode 0600, and never committed to git. Tokens are never printed or logged: auth status, auth refresh and push-railway show only expiry and success/failure
• Railway deployment — the token seeds live in Railway's env vars and the refreshed tokens live on the service volume. Use Railway's secrets management
• No password access — the plugin only captures the Bearer token, not your Rappi password

How the API Was Mapped

The Rappi API is undocumented. All 40+ endpoints were reverse-engineered by capturing browser network traffic from rappi.com.co using Chrome DevTools, assisted by reverse-api-engineer — a tool that automatically generates API clients from captured HAR traffic using AI analysis. The full API map is in API_ENDPOINTS.md.

Updating the app-version Header

Rappi deploys new versions regularly. If API calls start returning 403 errors:

1. Open your country's Rappi website in Chrome DevTools (Network tab)
2. Look at any API request's app-version header
3. Update APP_VERSION in src/rappi/constants.py
4. Also update WEB_VERSION if store browsing breaks

Development

uv sync --group dev            # Install dev dependencies
uv run rappi --help            # Test CLI
uv run pytest                  # Run tests
npx @modelcontextprotocol/inspector uv run rappi-mcp  # Test MCP in browser

See CLAUDE.md for the developer reference, API_ENDPOINTS.md for the full Rappi API map, and TESTING.md for the manual testing checklist.

Author

Gabriel Garavit — GitHub

Built with Claude Code. API reverse-engineered from Rappi's web app using browser DevTools and reverse-api-engineer.

License

MIT