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"
      }
    }
  }
}

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