Skip to main content
Glama
grubhub-mcp

grubhub-mcp

by aserper

Grubhub MCP Server

An MCP (Model Context Protocol) server that provides programmatic access to Grubhub's food delivery platform. Search restaurants, browse menus, manage your cart, place orders, and track deliveries — all through MCP tools.

Features

  • Search & Discovery — Find restaurants by location, cuisine, or keyword with autocomplete

  • Restaurant & Menus — View restaurant details, full menus, item options and pricing

  • Cart Management — Create carts, add/remove items, apply promo codes, set tips

  • Order Flow — Place orders, track deliveries in real-time, reorder past meals

  • Account Management — Manage profile, saved addresses, favorites, and passwords

  • Payments — View saved payment methods, check gift card balances

All 36 Tools

Category

Tools

Auth

login, logout, get_session_info, send_login_otp, verify_login_otp, create_account, send_password_reset

Search

search_restaurants, autocomplete_search

Restaurant

get_restaurant, get_menu, get_menu_item

Cart

create_cart, get_cart, add_to_cart, update_cart_item, remove_from_cart, apply_promo_code, set_tip

Order

place_order, get_order, get_order_history, track_order, reorder, post_delivery_tip

Account

get_profile, update_profile, get_addresses, add_address, get_favorites, add_favorite, remove_favorite, change_password

Payments

get_payment_methods, get_gift_card_balance, apply_gift_card

Related MCP server: doordash-mcp

Installation

claude plugin marketplace add aserper/grubhub-mcp
claude plugin install grubhub-mcp@grubhub-marketplace

uvx (No Installation Required)

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "grubhub": {
      "command": "uvx",
      "args": ["--from", "grubhub-mcp", "grubhub"]
    }
  }
}

Manual / From Source

Requires Python 3.11+.

git clone https://github.com/aserper/grubhub-mcp.git
cd grubhub-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

Then add to ~/.claude/settings.json:

{
  "mcpServers": {
    "grubhub": {
      "command": "/path/to/grubhub-mcp/.venv/bin/grubhub"
    }
  }
}

Usage with Other MCP Clients

Run the server over stdio:

# With uvx (no install needed)
uvx --from grubhub-mcp grubhub

# Or from a local install
grubhub

# Or as a Python module
python -m grubhub_mcp

Authentication

No login required for browsing — search restaurants, view menus, and check prices without an account. The server automatically creates an anonymous session.

Login required for ordering, account management, and order history:

Use the login tool with my email and password

Supports email/password login and OTP (one-time passcode) authentication.

Sessions are stored in ~/.grubhub-mcp/session.json (override the directory with GRUBHUB_SESSION_DIR). Access tokens are refreshed on use, including before expiry when Grubhub supplies expiry metadata and once after an authenticated request returns 401. Rotated tokens are saved for the next server invocation. Refresh responses that omit account metadata do not erase your login identity. Concurrent refreshes are serialized within the client, and on POSIX systems across server processes sharing the session directory. Session writes are atomic and use private file permissions. Grubhub's lifetime fields are in minutes; the observed access/refresh lifetimes are one hour / 30 days, but server policy may change. There is no background keep-alive: a revoked or expired refresh token still requires a new login. Do not share your session file; it contains credentials.

Order History Pagination

get_order_history uses server-side pagination so older orders are reachable. page_num is 1-based (default 1), and page_size defaults to 20. Iterate from 1 through pagination.total_pages to retrieve the full history. Both values must be positive. Order-detail and reorder fallbacks search across all available history pages.

Migration from v1.1.6: callers using the old 0-based page_num must add one to their page index. The response now provides total_pages and current_page instead of the legacy total_orders value, which only counted a capped subset.

How It Works

The API endpoints were reverse-engineered from the Grubhub Android app (v2026.11.1) by decompiling the APK with jadx and analyzing the Retrofit service interfaces, OkHttp interceptors, and data models.

Key technical details:

  • Base API: https://api-gtm.grubhub.com

  • Auth: Bearer token via email/password or anonymous sessions

  • Transport: REST/JSON for most endpoints, Protobuf for some BFF services

  • Headers: Mimics the Android app's request headers including x-gh-browser-id

Project Structure

src/grubhub_mcp/
├── __init__.py
├── __main__.py        # python -m entry point
├── server.py          # MCP server setup and tool registration
├── client.py          # HTTP client with auth and header management
├── auth.py            # Authentication flows (login, anonymous, OTP, refresh)
└── tools/
    ├── auth.py        # Auth tools (login, logout, OTP, account creation)
    ├── search.py      # Restaurant search and autocomplete
    ├── restaurant.py  # Restaurant details, menus, menu items
    ├── cart.py        # Cart CRUD, promo codes, tips
    ├── order.py       # Place orders, track, reorder, order history
    ├── account.py     # Profile, addresses, favorites, password
    └── payments.py    # Payment methods, gift cards

Development

Run the regression suite with:

uv run python -m unittest discover -s tests -v

CI runs tests on pushes and pull requests, and the release job runs them before publishing. The package currently requires MCP 1.x (mcp<2).

Disclaimer

This project is for educational and personal use. It is not affiliated with or endorsed by Grubhub. Use responsibly and in accordance with Grubhub's terms of service.

License

MIT

Available Tools

36 tools
add_addressB

Add a new delivery address. Requires authentication.

Args: street_address: Street address line city: City name state: State abbreviation (e.g. NY, CA) zip_code: ZIP code apt_suite: Apartment/suite number delivery_instructions: Special delivery instructions label: Label for the address (e.g. Home, Work)

Inputs: city (required), state (required), zip_code (required), street_address (required), +3 more. Returns: result

add_favoriteB

Add a restaurant to favorites. Requires authentication.

Args: restaurant_id: The restaurant ID to favorite

Inputs: restaurant_id (required). Returns: result

add_to_cartB

Add an item to an existing cart.

Args: cart_id: The cart ID to add to menu_item_id: The menu item ID to add quantity: Number of this item (default 1) special_instructions: Special preparation instructions options: List of selected options/add-ons, each with {id, quantity}

Inputs: cart_id (required), menu_item_id (required), options, quantity, +1 more. Returns: result

apply_gift_cardC

Apply a gift card to a cart.

Args: cart_id: The cart ID card_number: Gift card number pin: Gift card PIN

Inputs: pin (required), cart_id (required), card_number (required). Returns: result

apply_promo_codeC

Apply a promotion code to the cart.

Args: cart_id: The cart ID promo_code: The promotion code to apply

Inputs: cart_id (required), promo_code (required). Returns: result

change_passwordC

Change account password. Requires authentication.

Args: current_password: Current password new_password: New password

Inputs: new_password (required), current_password (required). Returns: result

create_accountC

Create a new Grubhub account.

Inputs: email (required), password (required), last_name (required), first_name (required). Returns: result

create_cartB

Create a new cart with the first item.

Args: restaurant_id: The restaurant ID to order from menu_item_id: The menu item ID to add quantity: Number of this item (default 1) special_instructions: Special preparation instructions options: List of selected options/add-ons, each with {id, quantity} latitude: Delivery latitude longitude: Delivery longitude is_delivery: True for delivery, False for pickup

Inputs: menu_item_id (required), restaurant_id (required), options, latitude, +4 more. Returns: result

get_addressesA

Get saved delivery addresses. Requires authentication.

Inputs: no named parameters. Returns: result

get_cartB

Get the current state of a cart including items, totals, and fees.

Args: cart_id: The cart ID

Inputs: cart_id (required). Returns: result

get_favoritesB

Get favorite/saved restaurants. Requires authentication.

Inputs: no named parameters. Returns: result

get_gift_card_balanceC

Check the balance of a Grubhub gift card.

Args: card_number: Gift card number pin: Gift card PIN

Inputs: pin (required), card_number (required). Returns: result

get_menuA

Get the full menu for a restaurant including categories, items, and prices.

This is the same as get_restaurant — the v4 endpoint returns the full menu.

Args: restaurant_id: The Grubhub restaurant ID latitude: Optional latitude for availability longitude: Optional longitude for availability

Inputs: restaurant_id (required), latitude, longitude. Returns: result

get_menu_itemB

Get details for a specific menu item including options, add-ons, and pricing.

Args: restaurant_id: The Grubhub restaurant ID item_id: The menu item ID order_type: Order type - standard, catering (default standard) latitude: Optional latitude for availability longitude: Optional longitude for availability

Inputs: item_id (required), restaurant_id (required), latitude, longitude, +1 more. Returns: result

get_orderC

Get details for a specific order.

Args: order_id: The order ID

Inputs: order_id (required). Returns: result

get_order_historyA

Get past order history (paginated). Requires authentication.

Pagination is server-side via the search_listing endpoint, so the full history is reachable -- iterate page_num from 1 up to pagination.total_pages in the response.

Args: page_size: Orders per page (default 20) page_num: 1-based page number (default 1)

Inputs: page_num, page_size. Returns: result

get_payment_methodsB

Get saved payment methods. Requires authentication.

Inputs: no named parameters. Returns: result

get_profileA

Get the current user's profile information. Requires authentication.

Inputs: no named parameters. Returns: result

get_restaurantB

Get restaurant details including menu, hours, ratings, and delivery info.

Args: restaurant_id: The Grubhub restaurant ID latitude: Optional latitude for delivery estimates longitude: Optional longitude for delivery estimates order_type: Order type - standard, catering (default standard)

Inputs: restaurant_id (required), latitude, longitude, order_type. Returns: result

get_session_infoA

Get current authentication state and session info.

Inputs: no named parameters. Returns: result

loginC

Log in to Grubhub with email and password. Returns session info on success.

Inputs: email (required), password (required). Returns: result

logoutA

Log out of the current Grubhub session.

Inputs: no named parameters. Returns: result

place_orderB

Place an order from a cart. Requires authentication.

Args: cart_id: The cart ID to submit as an order payment_method_id: ID of the payment method to use (uses default if not specified) tip_amount: Optional tip amount in dollars

Inputs: cart_id (required), tip_amount, payment_method_id. Returns: result

post_delivery_tipB

Add or update the tip after delivery.

Args: order_id: The order ID tip_amount: Tip amount in dollars

Inputs: order_id (required), tip_amount (required). Returns: result

remove_favoriteB

Remove a restaurant from favorites. Requires authentication.

Args: restaurant_id: The restaurant ID to unfavorite

Inputs: restaurant_id (required). Returns: result

remove_from_cartC

Remove an item from the cart.

Args: cart_id: The cart ID line_item_id: The line item ID to remove

Inputs: cart_id (required), line_item_id (required). Returns: result

reorderB

Create a new cart from a previous order for easy reordering.

Args: order_id: The order ID to reorder

Inputs: order_id (required). Returns: result

search_restaurantsB

Search for restaurants near a location.

Args: latitude: Latitude of the delivery address longitude: Longitude of the delivery address query: Optional search query (cuisine, restaurant name, dish) page_size: Number of results per page (default 20) page_num: Page number for pagination (1-based, default 1) sort_type: Optional sort — leave empty for default relevance location_mode: DELIVERY or PICKUP (default DELIVERY)

Inputs: latitude (required), longitude (required), query, page_num, +3 more. Returns: result

send_login_otpB

Send a one-time passcode to the given email for login.

Inputs: email (required). Returns: result

send_password_resetC

Send a password reset OTP to the given email.

Inputs: email (required). Returns: result

set_tipC

Set the tip amount on the cart.

Args: cart_id: The cart ID tip_amount: Tip amount in dollars

Inputs: cart_id (required), tip_amount (required). Returns: result

track_orderB

Get real-time tracking info for an active order.

Args: order_id: The order ID to track

Inputs: order_id (required). Returns: result

update_cart_itemB

Update the quantity of an item in the cart.

Args: cart_id: The cart ID line_item_id: The line item ID to update quantity: New quantity (0 to remove)

Inputs: cart_id (required), quantity (required), line_item_id (required). Returns: result

update_profileC

Update user profile information. Requires authentication.

Args: first_name: New first name last_name: New last name phone: New phone number

Inputs: phone, last_name, first_name. Returns: result

verify_login_otpA

Verify a one-time passcode and complete login.

Inputs: code (required), email (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, but get_restaurant and get_menu are explicitly documented as returning the same data ('This is the same as get_restaurant'), creating a real selection ambiguity. The set_tip vs post_delivery_tip and create_cart vs add_to_cart pairs are reasonably differentiated by context.

    Naming Consistency5/5

    Nearly all tools follow a consistent snake_case verb_noun pattern (get_restaurant, create_cart, apply_promo_code, send_login_otp). The bare login/logout exceptions are conventional and unambiguous.

    Tool Count3/5

    36 tools is heavy for this domain. The cart, order, search, and profile groups each earn their place, but the eight auth/account tools (login, logout, get_session_info, two OTP flows, create_account, reset, change_password) are bloated relative to need.

    Completeness4/5

    Strong lifecycle coverage: auth, search, restaurant/menu browsing, cart management, ordering, tracking, reorder, profile, addresses, payment, and favorites. Minor gaps like no remove/update address, no add payment method, and no order cancellation keep it short of full coverage.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers