grubhub-mcp
Provides programmatic access to Grubhub's food delivery platform, including restaurant search and discovery, menu browsing, cart management, order placement and tracking, account and address management, payment methods, and gift card balance checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grubhub-mcp find Italian restaurants in downtown Seattle"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
Search |
|
Restaurant |
|
Cart |
|
Order |
|
Account |
|
Payments |
|
Related MCP server: doordash-mcp
Installation
Claude Code Plugin (Recommended)
claude plugin marketplace add aserper/grubhub-mcp
claude plugin install grubhub-mcp@grubhub-marketplaceuvx (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_mcpAuthentication
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 passwordSupports 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.comAuth: 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 cardsDevelopment
Run the regression suite with:
uv run python -m unittest discover -s tests -vCI 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 toolsadd_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
autocomplete_searchB
Get autocomplete suggestions for a search query.
Args: query: The partial search text latitude: Latitude for location context longitude: Longitude for location context location_mode: DELIVERY or PICKUP (default DELIVERY)
Inputs: query (required), latitude (required), longitude (required), location_mode. 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_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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
DoorDash MCP server for ChatGPT, Claude and any AI agent: search stores, read store menu, add item to cart, preview order total with fees, submit order, list past orders, get order status and reorder a past order in your own DoorDash account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to DoorDash yourself; Cotlet does not store your password and you need no DoorDash API key. About the official DoorDash API: DoorDash has no public API for ordering as a consumer (checked 27 Oct 2026). Its public APIs, Drive and Marketplace, are for merchants and delivery partners. Setup and FAQ: https://cotlet.dev/integrations/doordash-api-mcp-server
Per-restaurant MCP servers: menu, hours, delivery terms; live example below
Restaurant menus, carts, reservations and owner drafts for AI agents (Thmenu MCP).
Search multi-merchant supply, checkout, and track orders via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to discover restaurants and place food delivery orders on Uber Eats and Thuisbezorgd (Just Eat Takeaway). It provides tools for restaurant discovery and order management through normalized platform APIs.5MIT
- FlicenseBqualityDmaintenanceEnables AI agents to search restaurants, browse menus, manage carts, and place orders on DoorDash programmatically. It utilizes a headless browser to interact with DoorDash's GraphQL API and bypass anti-bot protections for the full delivery lifecycle.224-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to autonomously order food from Grubhub, including searching restaurants, browsing menus, managing cart, placing orders, and tracking delivery.41 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Uber Eats for food ordering and delivery management through natural language, acting as a proof-of-concept MCP integration.-