piree-ondc-mcp

ONDC MCP Server — Connect AI agents to India's Open Network for Digital Commerce (ONDC) via the Beckn protocol. Part of the Piree trust infrastructure for AI agents.

Installation

npx piree-ondc-mcp

Or install globally:

npm install -g piree-ondc-mcp
piree-ondc-mcp

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ondc": {
      "command": "npx",
      "args": ["-y", "piree-ondc-mcp"],
      "env": {
        "ONDC_MOCK": "true"
      }
    }
  }
}

For production with live ONDC sandbox:

{
  "mcpServers": {
    "ondc": {
      "command": "npx",
      "args": ["-y", "piree-ondc-mcp"],
      "env": {
        "ONDC_GATEWAY_URL": "https://pilot-gateway-1.beckn.nsdl.co.in",
        "ONDC_BAP_ID": "your-bap-id.example.com",
        "ONDC_BAP_URI": "https://your-callback-url.example.com",
        "PIREE_KYA_API_URL": "https://api.piree.ai"
      }
    }
  }
}

Tools

1. ondc_search — Search Products

Search the ONDC network for products using natural language.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Natural language query, e.g. "organic basmati rice 5kg" | | category | string | No | ONDC category code, e.g. "ONDC:RET10" (grocery) | | location.city | string | No | City name for delivery filtering | | location.pincode | string | No | 6-digit pincode for delivery filtering | | price_range.min | number | No | Minimum price in INR | | price_range.max | number | No | Maximum price in INR | | price_range.currency | "INR" | No | Currency (only INR supported) | | limit | number | No | Max results (1–50, default 10) |

Example:

Search for organic rice under ₹500 deliverable to Bengaluru 560001

2. ondc_get_product — Get Product Details

Retrieve full details for a specific product by ID.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | product_id | string | Yes | Product ID from search results | | provider_id | string | Yes | Merchant/provider ID from search results |

3. ondc_get_merchant — Get Merchant Details

Retrieve merchant profile, locations, ratings and compliance information.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | provider_id | string | Yes | Merchant/provider ID from search results |

4. ondc_check_availability — Check Delivery Availability

Check whether a product can be delivered to a specific pincode.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | product_id | string | Yes | Product ID | | provider_id | string | Yes | Merchant/provider ID | | delivery_location.city | string | Yes | Destination city | | delivery_location.pincode | string | Yes | 6-digit destination pincode |

5. ondc_initiate_order — Initiate Order (KYA-gated)

Place an order on the ONDC network. Requires an Piree Machine Passport credential. Obtain one at register.piree.ai.

Discovery tools (1–4 above) are free and require no credentials.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | product_id | string | Yes | Product ID | | provider_id | string | Yes | Merchant/provider ID | | quantity | number | Yes | Number of units | | delivery_address.name | string | Yes | Recipient full name | | delivery_address.address | string | Yes | Street address | | delivery_address.city | string | Yes | City | | delivery_address.pincode | string | Yes | 6-digit pincode | | delivery_address.phone | string | Yes | 10-12 digit phone number | | agent_credential | string | Yes | Piree Machine Passport JWT |

6. ondc_get_order_status — Get Order Status

Track the status of a placed order.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | order_id | string | Yes | Order ID from ondc_initiate_order |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ONDC_MOCK | false | Set to true for mock mode (no real ONDC calls) | | ONDC_GATEWAY_URL | https://pilot-gateway-1.beckn.nsdl.co.in | ONDC gateway URL | | ONDC_BAP_ID | piree.ai | Your Beckn BAP (Buyer App) ID | | ONDC_BAP_URI | http://localhost:3000 | Your callback URL (must be publicly reachable) | | ONDC_DEFAULT_DOMAIN | ONDC:RET10 | Default ONDC domain (grocery) | | ONDC_DEFAULT_CITY | std:080 | Default city code (Bengaluru) | | PIREE_KYA_API_URL | https://api.piree.ai | Piree KYA verification API URL | | PIREE_MOCK_KYA | false | Set to true to skip JWT verification (dev only) | | PIREE_KYA_ISSUER | did:web:piree.ai | Expected JWT issuer for credential verification |

Mock Mode

Set ONDC_MOCK=true to run against a built-in mock catalog. No ONDC sandbox credentials required.

The mock catalog includes:

• Organic Basmati Rice 5kg — ₹450 (Fresh Farms)
• Cold Pressed Coconut Oil 1L — ₹280 (Fresh Farms)
• Organic Toor Dal 1kg — ₹165 (Organic India Store)
• Whole Wheat Atta 10kg — ₹520 (Organic India Store)
• Desi Ghee 500ml — ₹650 (Gaushala Products)

ONDC_MOCK=true PIREE_MOCK_KYA=true npx piree-ondc-mcp

ONDC Sandbox Registration

To connect to the live ONDC sandbox:

1. Register at https://ondc.org/get-registered/
2. Apply for sandbox access (approval takes 1–2 weeks)
3. Set ONDC_BAP_ID and ONDC_BAP_URI with your approved credentials
4. Your ONDC_BAP_URI must be a publicly reachable HTTPS URL (use ngrok in development: ngrok http 3000)
5. Register the /on_search, /on_select, /on_init, /on_confirm, /on_status callback endpoints

Beckn Protocol Architecture

ONDC uses Beckn protocol v2, which is asynchronous with callbacks — not request/response:

Agent → MCP Tool → BAP (/search) → ONDC Gateway → BPPs
                                                     ↓
Agent ← MCP Tool ← BAP (/on_search) ←─────────────── BPPs

This server uses a pending-request map pattern to bridge async Beckn callbacks into synchronous MCP tool responses. Each request registers a resolver keyed by message_id. The /on_* callback handler resolves the promise. An 8-second timeout returns empty results if no callback arrives.

ONDC Domain Codes

| Domain | Category | |--------|----------| | ONDC:RET10 | Grocery & Staples | | ONDC:RET12 | Fashion & Apparel | | ONDC:RET14 | Electronics | | ONDC:RET15 | Appliances | | ONDC:RET16 | Home & Kitchen | | ONDC:RET17 | Health & Beauty | | ONDC:RET18 | Toys & Games |

License

MIT — Piree