# Ifood Mcp

> MCP server for iFood — merchant integration, orders (Brazil). Part of WWmcp — 114 MCP servers for emerging markets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-theyahia-ifood-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [theYahia](https://agentstack.voostack.com/s/theyahia)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [theYahia](https://github.com/theYahia)
- **Source:** https://github.com/theYahia/ifood-mcp

## Install

```sh
agentstack add mcp-theyahia-ifood-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ifood-mcp

MCP server for [iFood](https://www.ifood.com.br/) merchant integration (Brazil) — manage orders, the store, and the catalog from any MCP client (Claude, etc.).

Talks to the iFood **Merchant API** (`merchant-api.ifood.com.br`) using OAuth2 `client_credentials`. One shared, auto-refreshed token is used across all tools.

## Quick Start

```json
{
  "mcpServers": {
    "ifood": {
      "command": "npx",
      "args": ["-y", "@theyahia/ifood-mcp"],
      "env": {
        "IFOOD_CLIENT_ID": "",
        "IFOOD_CLIENT_SECRET": ""
      }
    }
  }
}
```

Get credentials from the [iFood Developer Portal](https://developer.ifood.com.br/) (create an application; this server uses the `client_credentials` grant, which reaches the merchants your application directly owns).

## Order workflow

iFood delivers orders as **events** you must poll and acknowledge:

1. `list_orders` — poll for new events (~every 30s). Returns events like `PLACED`, `CONFIRMED`, `CANCELLED`.
2. `acknowledge_events` — acknowledge the event IDs you received, or **iFood redelivers them on every poll forever**.
3. `get_order` — fetch full detail for an order ID from a `PLACED` event.
4. `confirm_order` → `start_preparation` (optional) → `dispatch_order` (delivery) **or** `ready_to_pickup` (takeout/dine-in).
5. To cancel: `get_cancellation_reasons` (get valid codes for that order) → `cancel_order` (with a code).

## Tools (26)

### Orders
| Tool | What it does |
|---|---|
| `list_orders` | Poll order events (PLACED/CONFIRMED/…). |
| `acknowledge_events` | Acknowledge events so they stop being redelivered. |
| `get_order` | Get full order detail by ID. |
| `confirm_order` | Confirm/accept an order. |
| `start_preparation` | Mark an order as in preparation (optional). |
| `ready_to_pickup` | Mark an order ready for pickup (required for takeout/dine-in). |
| `dispatch_order` | Mark a delivery order as dispatched. |
| `get_cancellation_reasons` | Get valid cancellation codes for an order. |
| `cancel_order` | Request cancellation using a code. |

### Merchant
| Tool | What it does |
|---|---|
| `list_merchants` | List accessible merchants (paginated). |
| `get_merchant` | Full merchant detail (name, address, operations). |
| `get_merchant_status` | Availability per operation/sales channel. |
| `get_opening_hours` | Read weekly opening hours. |
| `set_opening_hours` | Replace the entire weekly schedule. |
| `list_interruptions` | List active/future store pauses. |
| `create_interruption` | Temporarily pause the store (the correct pause mechanism). |
| `delete_interruption` | Resume the store. |

### Catalog (v2.0)
| Tool | What it does |
|---|---|
| `update_item_status` | Set an item AVAILABLE/UNAVAILABLE. |
| `update_item_price` | Update an item's price. |
| `update_option_status` | Set a complement/option AVAILABLE/UNAVAILABLE. |
| `update_option_price` | Update a complement/option price. |
| `list_catalogs` | List the merchant's catalogs. |
| `list_categories` | List categories (use `include_items` to get item IDs). |
| `list_items_by_category` | List items/products/options in a category. |
| `list_products` | List products (paginated). |
| `upsert_item` | Create or fully replace an item with its dependencies. |

To discover an `item_id` for the write tools: `list_merchants` → `list_catalogs` → `list_categories` (`include_items: true`).

Tools carry MCP [annotations](https://modelcontextprotocol.io/) (`readOnlyHint` / `destructiveHint` / `idempotentHint`) so clients can warn before write/destructive actions.

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `IFOOD_CLIENT_ID` | Yes | — | OAuth client ID. |
| `IFOOD_CLIENT_SECRET` | Yes | — | OAuth client secret. |
| `IFOOD_BASE_URL` | No | `https://merchant-api.ifood.com.br` | Override the API base URL (staging/sandbox). |
| `IFOOD_TOKEN_URL` | No | `/authentication/v1.0/oauth/token` | Override the token endpoint. |
| `IFOOD_TIMEOUT_MS` | No | `15000` | Per-request timeout in ms. |
| `IFOOD_MAX_ATTEMPTS` | No | `3` | Total attempts (initial + retries) for transient failures. |

The client automatically: retries `429`/`5xx`/network/timeout with exponential backoff (honoring `Retry-After`), refreshes the OAuth token once on a `401`, and tolerates the empty `202`/`204` bodies iFood returns for state transitions.

## Troubleshooting

- **401 / auth errors** — check `IFOOD_CLIENT_ID`/`IFOOD_CLIENT_SECRET`; the client re-auths once automatically on a mid-session 401.
- **Empty merchant list** — `client_credentials` only reaches merchants your application directly owns. The iFood *distribution* model (per-merchant `authorization_code` tokens) is not implemented here.
- **429 rate limit** — `list_orders` polling is limited to ~one request per 30s per token; the client backs off automatically.
- **`get_order` 404 right after PLACED** — order detail can lag the event; retry with backoff (up to ~10 min).

## ⚠️ Endpoints pending verification

iFood's developer portal blocks automated access, so two endpoints were implemented from best available (cross-source) evidence rather than a verbatim spec read. **Verify against the live iFood docs / Postman collection before depending on them in production** (see code comments in the relevant tool files):

- **`acknowledge_events`** — uses `POST /order/v1.0/events/acknowledgment`. The `events` path segment is a best-guess (the alternative is `/order/v1.0/acknowledgment`).
- **`cancel_order`** — sends `{ "reason": "" }`. The exact order-module body is uncertain (a two-field `{ reason, cancellationCode }` shape may belong to the shipping module).

## Development

```bash
npm ci
npm run build      # tsc → dist/
npm test           # vitest
npm run dev        # tsx src/index.ts
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [theYahia](https://github.com/theYahia)
- **Source:** [theYahia/ifood-mcp](https://github.com/theYahia/ifood-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-theyahia-ifood-mcp
- Seller: https://agentstack.voostack.com/s/theyahia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.