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: intelligence-api

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