Skip to main content
Glama

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/authKey

  • saved 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 build

Run locally:

npm start

MCP 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

  1. Call ninja_auth_start_login with the account phone number. This registers a device session and sends an OTP.

  2. Call ninja_auth_verify_otp with the OTP.

  3. 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.json

Override with:

NINJA_MCP_STATE_FILE=/secure/path/state.json

State files contain auth material.

Current Coverage

Implemented:

  • auth/device session reuse

  • saved address listing

  • vertical discovery for RETAIL, PHARMACY, BEAUTY, and RESTAURANT

  • product 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.cardId with optional savedCard.cvv

  • wallet payment request shape: includeWallet: true

  • restaurant checkout request shape: OrderRequest.restaurant with branchId and menuId, plus restaurant variant IDs in lineItems[].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.pharmacy passthrough

Agent Workflow

Read ninja://agent-guide or call ninja_agent_guide first.

Typical product-vertical call sequence:

  1. ninja_saved_addresses

  2. ninja_search_products with vertical: "RETAIL", "PHARMACY", or "BEAUTY"

  3. ninja_create_draft_order

  4. Review the exact cart, total, delivery location, and payment method.

  5. ninja_create_checkout with confirmCreateOrder: true

  6. ninja_pending_payment_methods

  7. Choose from the available payment methods.

  8. Use a method-specific helper if this MCP implements that method.

Typical restaurant call sequence:

  1. ninja_saved_addresses

  2. ninja_search_restaurants

  3. ninja_restaurant_menu

  4. ninja_create_draft_order with vertical: "RESTAURANT", restaurant.branchId, restaurant.menuId, and restaurant variant IDs in lineItems[].itemId

  5. Review the draft, then continue through checkout/payment if the cart is correct.

Implemented method-specific helpers:

  • saved card: call ninja_pending_payment_methods, choose a cardIndex, then call ninja_pay_saved_card

  • wallet: call ninja_pay_wallet if wallet is available for the pending checkout

  • STC Pay: use ninja_initiate_stc_pay, collect the fresh OTP, then call ninja_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 as imageUrls.

  • Retail/pharmacy/beauty product search returns both id and productId. Use productId, exposed as orderItemId, for lineItems[].itemId. The id field is store-scoped and should not be used as the cart item id.

  • Restaurant carts use menu variant IDs. Use variant.orderItemId / variantId from ninja_restaurant_menu for lineItems[].itemId.

  • Restaurant toppings use toppingId and toppingOptionId from the menu response.

  • createDraftOrder.paymentMethods is a direct list, not a { data: [...] } wrapper.

  • Always draft before checkout/payment.

  • createOrder can 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_methods labels each method with apiCapability and mcpCapability.

  • Saved cards expose requiresCvv; saved-card payment accepts cardIndex or cardId, plus optional cvv.

  • ninja_saved_payment_options lists account-level saved cards and wallets; for an actual checkout, prefer ninja_pending_payment_methods.

  • STC Pay initiate expects mobileNumber in 9665XXXXXXXX form; the MCP normalizes common Saudi formats.

  • Payment calls can return PENDING; poll paymentStatus and then inspect showOrder.

  • 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, and confirmSubmitPayment.

  • 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_override

Available Tools

19 tools
ninja_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_restaurant_menuGet Restaurant MenuC

Fetch a restaurant branch menu. Menu output includes menuId, product imageUrls, variant orderItemId values, and topping/modifier ids.

Inputs: branchId (required), maxProductsPerCategory.

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

    B3.2/5.0

    Scored across 19 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case and the 'ninja_' prefix. No mixed conventions or unpredictable naming.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Mindbody, enabling AI agents to fetch client info, query class schedules, book classes/appointments (env-gated), and process checkout (payment-gated).
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      17
      MIT