Ninja MCP
Allows inspection of Apple Pay as a payment method for the Ninja/AnaNinja mobile API, including availability and details for pending checkouts.
Allows inspection of Google Pay as a payment method for the Ninja/AnaNinja mobile API, including availability and details for pending checkouts.
Allows inspection of Samsung Pay as a payment method for the Ninja/AnaNinja mobile API, including availability and details for pending checkouts.
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., "@Ninja MCP search for organic milk in Riyadh"
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.
Unofficial Ninja MCP
MCP server for AI agents working with the Ninja/AnaNinja API.
This project exposes the Ninja/AnaNinja API as a small operational MCP:
auth with reusable local
deviceId/authKeysaved addresses
vertical/store discovery for retail, pharmacy, beauty, and restaurants
retail/pharmacy/beauty product search, detail lookup, and product image URLs
restaurant branch search, menu lookup, variant IDs, and topping metadata
draft order validation for product verticals and restaurants
guarded checkout creation
payment-method inspection plus saved-card, wallet, and STC Pay helpers
Live checkout/payment tools use explicit execution flags and keep state in local 0600 files.
Install
npm install
npm run buildRun locally:
npm startMCP client config example:
{
"mcpServers": {
"ninja": {
"command": "node",
"args": ["/absolute/path/to/ninja-mcp/dist/index.js"],
"env": {
"NINJA_MCP_STATE_FILE": "/Users/you/.ninja-mcp/state.json"
}
}
}
}Related MCP server: wolt-mcp
First Login
Call
ninja_auth_start_loginwith the account phone number. This registers a device session and sends an OTP.Call
ninja_auth_verify_otpwith the OTP.Future calls reuse the saved auth key. This MCP does not use an OAuth refresh-token flow.
The default state path is:
~/.ninja-mcp/state.jsonOverride with:
NINJA_MCP_STATE_FILE=/secure/path/state.jsonState files contain auth material.
Current Coverage
Implemented:
auth/device session reuse
saved address listing
vertical discovery for
RETAIL,PHARMACY,BEAUTY, andRESTAURANTproduct search and detail lookup for retail/pharmacy/beauty through the Fahras products endpoint
product image URL extraction from product and restaurant menu media
restaurant branch search and restaurant menu lookup through GraphQL
draft order validation for retail, pharmacy OTC, beauty, and restaurant carts
checkout creation for pending unpaid orders/payment requests
payment-method inspection for a pending checkout
account-level saved payment option inspection
payment helpers for saved card and wallet
STC Pay initiate + OTP helper flow
MCP request-shape support:
saved-card payment request shape:
savedCard.cardIdwith optionalsavedCard.cvvwallet payment request shape:
includeWallet: truerestaurant checkout request shape:
OrderRequest.restaurantwithbranchIdandmenuId, plus restaurant variant IDs inlineItems[].itemId
Not implemented by this MCP:
Tabby/Tamara and other redirect/token-based methods
Apple Pay, Samsung Pay, Google Pay, QPay, KNET, Benefit, Daftar
prescription/consultation pharmacy handling beyond
request.pharmacypassthrough
Agent Workflow
Read ninja://agent-guide or call ninja_agent_guide first.
Typical product-vertical call sequence:
ninja_saved_addressesninja_search_productswithvertical: "RETAIL","PHARMACY", or"BEAUTY"ninja_create_draft_orderReview the exact cart, total, delivery location, and payment method.
ninja_create_checkoutwithconfirmCreateOrder: trueninja_pending_payment_methodsChoose from the available payment methods.
Use a method-specific helper if this MCP implements that method.
Typical restaurant call sequence:
ninja_saved_addressesninja_search_restaurantsninja_restaurant_menuninja_create_draft_orderwithvertical: "RESTAURANT",restaurant.branchId,restaurant.menuId, and restaurant variant IDs inlineItems[].itemIdReview the draft, then continue through checkout/payment if the cart is correct.
Implemented method-specific helpers:
saved card: call
ninja_pending_payment_methods, choose acardIndex, then callninja_pay_saved_cardwallet: call
ninja_pay_walletif wallet is available for the pending checkoutSTC Pay: use
ninja_initiate_stc_pay, collect the fresh OTP, then callninja_submit_stc_otp
Card setup: card registration is outside this MCP. Add a saved card to the account, then refresh ninja_saved_payment_options or ninja_pending_payment_methods. Once the card appears as saved, use ninja_pay_saved_card.
API Notes
The bearer token is a short-lived HS256 JWT signed locally with
authKey.Saved addresses are backend GraphQL data, not only local client memory.
Product search uses vertical discovery to find the store/search context, then the Fahras products endpoint.
Product image URLs come from
medias; search/menu tools return them asimageUrls.Retail/pharmacy/beauty product search returns both
idandproductId. UseproductId, exposed asorderItemId, forlineItems[].itemId. Theidfield is store-scoped and should not be used as the cart item id.Restaurant carts use menu variant IDs. Use
variant.orderItemId/variantIdfromninja_restaurant_menuforlineItems[].itemId.Restaurant toppings use
toppingIdandtoppingOptionIdfrom the menu response.createDraftOrder.paymentMethodsis a direct list, not a{ data: [...] }wrapper.Always draft before checkout/payment.
createOrdercan recover the same pending payment request for the same cart.Payment methods are returned per payment request; availability can vary by account, cart, location, and time.
ninja_pending_payment_methodslabels each method withapiCapabilityandmcpCapability.Saved cards expose
requiresCvv; saved-card payment acceptscardIndexorcardId, plus optionalcvv.ninja_saved_payment_optionslists account-level saved cards and wallets; for an actual checkout, preferninja_pending_payment_methods.STC Pay initiate expects
mobileNumberin9665XXXXXXXXform; the MCP normalizes common Saudi formats.Payment calls can return
PENDING; pollpaymentStatusand then inspectshowOrder.Totals are read from known payment-summary keys. If the upstream shape changes, the MCP reports candidate keys instead of guessing from an arbitrary amount.
State And Side Effects
Tool outputs redact full auth/payment IDs.
Auth state and pending payment context are written with mode
0600.Live mutation tools use execution flags, such as
confirmCreateOrder,confirmSendOtp,confirmSubmitOtp, andconfirmSubmitPayment.Failed payment attempts keep pending context so callers can try another available method.
Successful payment clears pending checkout context.
Environment
NINJA_MCP_STATE_FILE=/secure/path/state.json
NINJA_FIREBASE_CHECK_TOKEN=optional_firebase_check_token
NINJA_CLIENT_VERSION=optional_api_client_version_override
NINJA_CLIENT_USER_AGENT=optional_api_user_agent_overrideAvailable Tools
19 toolsninja_agent_guideRead Ninja Agent GuideB
Return the condensed guide for agents using this MCP.
Inputs: no named parameters.
ninja_auth_start_loginStart Ninja OTP LoginA
Register a device session and start phone login. This sends an OTP.
Inputs: mobileNumber (required).
ninja_auth_statusNinja Auth StatusA
Check whether local Ninja device auth state exists without exposing secrets.
Inputs: no named parameters.
ninja_auth_verify_otpVerify Ninja Login OTPA
Verify the one-time Ninja login OTP. After this, the saved device auth key can be reused by this MCP.
Inputs: otp (required).
ninja_create_checkoutCreate Payable CheckoutA
Create or recover a pending Ninja checkout/payment request. This creates an unpaid order/payment request; it does not pay.
Inputs: addressId (required), lineItems (required), confirmCreateOrder (required), notes, +6 more.
ninja_create_draft_orderCreate Draft OrderB
Validate a cart and pricing without creating a payable checkout. Supports retail, pharmacy OTC, beauty, and restaurant variant/topping line items.
Inputs: addressId (required), lineItems (required), notes, pharmacy, +5 more.
ninja_discover_retail_contextDiscover Retail Context (Alias)C
Compatibility alias for retail/grocery store/search context. Prefer ninja_discover_vertical_context for new agents.
Inputs: latitude, addressId, longitude.
ninja_discover_vertical_contextDiscover Vertical ContextB
Resolve vertical availability for a saved address or coordinates. Product verticals include store/search context; restaurants use separate branch/menu tools.
Inputs: latitude, vertical, addressId, longitude.
ninja_initiate_stc_payInitiate STC PayB
Initiate STC Pay for the saved pending checkout. Sends a fresh STC Pay OTP.
Inputs: mobileNumber (required), confirmSendOtp (required).
ninja_pay_saved_cardPay Saved CardA
Pay the saved pending checkout with a saved card. Use cardIndex from ninja_pending_payment_methods or provide a full cardId if known.
Inputs: confirmSubmitPayment (required), cvv, cardId, cardIndex, +3 more.
ninja_pay_walletPay WalletC
Pay the saved pending checkout using wallet balance.
Inputs: confirmSubmitPayment (required), pollCount.
ninja_pending_payment_methodsPending Checkout Payment MethodsA
Inspect methods for the saved pending checkout payment request before choosing any payment flow.
Inputs: no named parameters.
ninja_saved_addressesList Saved Ninja AddressesA
List saved addresses. Coordinates are approximate by default to avoid leaking exact home/work locations.
Inputs: includeExactCoordinates.
ninja_saved_payment_optionsSaved Payment OptionsA
List account-level payment options, saved cards, and wallets for an optional amount. Use pending checkout methods for actual checkout availability.
Inputs: amount.
ninja_search_productsSearch Ninja ProductsC
Search retail, pharmacy, or beauty products using Ninja's Fahras endpoint. Returns imageUrls and orderItemId/productId for cart line items.
Inputs: limit, query, latitude, vertical, +5 more.
ninja_search_restaurantsSearch Ninja RestaurantsA
Search restaurant branches near a saved address or coordinates. Use branchId with ninja_restaurant_menu before drafting a restaurant order.
Inputs: limit, query, itemId, latitude, +7 more.
ninja_show_pending_orderShow Pending OrderA
Show redacted order/payment status for the saved pending checkout.
Inputs: no named parameters.
ninja_submit_stc_otpSubmit STC Pay OTPC
Submit an STC Pay OTP. This can complete payment and place the order.
Inputs: otp (required), confirmSubmitOtp (required), pollCount.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clear distinct purposes, but ninja_discover_retail_context is a deprecated alias for ninja_discover_vertical_context, causing slight overlap. Other tools like the two OTP verification ones are for different flows.
All tools follow a consistent verb_noun pattern with snake_case and the 'ninja_' prefix. No mixed conventions or unpredictable naming.
19 tools is slightly above the ideal 3-15 range, but still reasonable for a comprehensive ordering and payment system covering auth, checkout, payments, search, and more.
The set covers the main checkout and payment workflow, but lacks tools for updating or cancelling orders, viewing order history, or managing cart items. These gaps could cause agent failures.
Maintenance
Related MCP Connectors
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
Multi-tenant MCP gateway for AI commerce. One connection, every store.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that wraps Shopify, Amazon, and Google Maps intelligence tools. AI agents pay autonomously in USDC on Base via x402 — no API keys or accounts needed.62MIT
- AlicenseAqualityDmaintenanceA thin MCP server that exposes Wolt's public consumer endpoints to AI agents, enabling discovery of nearby venues and fetching their menus with live prices and deal signals.2MIT
- AlicenseAqualityDmaintenanceMCP server for Mindbody, enabling AI agents to fetch client info, query class schedules, book classes/appointments (env-gated), and process checkout (payment-gated).5MIT
- AlicenseAqualityDmaintenanceMCP server that connects AI agents to Codinfy platform APIs for validating licenses, creating checkouts, listing products, tracking analytics, managing OAuth identity, and handling ad placements.17MIT