Beckn Mobility MCP Server
A generic Model Context Protocol (MCP) server for the Beckn Mobility domain. This server acts as a Buyer Application Platform (BAP), enabling AI agents (like Claude, Gemini, etc.) to search for cabs, view prices, and book rides using the open Beckn Protocol (e.g., Namma Yatri, ONDC).
Features
- Generic BAP Implementation: Connects to any Beckn-compliant Mobility BPP.
- MCP Tools: Exposes
search_cabs,select_ride,init_booking, andconfirm_bookingas AI tools. - Async Webhook Handling: Robust
WebhookManagerhandles Beckn's asynchronous callbacks with timeouts and request correlation. - Secure Signing: Implements Ed25519 request signing required by the Beckn Registry.
- Hono Server: Built on Hono for high-performance HTTP handling and Server-Sent Events (SSE).
- Verification Scripts: Includes a suite of scripts to verify crypto signing and end-to-end flows.
Prerequisites
- Node.js v18+
- A public URL (using
ngrokor a cloud deployment) for receiving webhooks. - Registration with a Beckn Registry (e.g., Namma Yatri Sandbox).
Installation
-
Clone the repository:
git clone https://github.com/<YOUR_USERNAME>/mcp-beckn-mobility.git cd mcp-beckn-mobility -
Install dependencies:
npm install
Configuration
-
Generate Keys: Run the helper script to generate your Ed25519 signing keys.
npx tsx src/generate_keys.tsCopy the output (BAP ID, Public Key, Private Key).
-
Setup Environment: Copy
.env.exampleto.env(or create it) and fill in your details:# Beckn Registry Details BAP_ID=mcp-mobility-bap-<TIMESTAMP> UNIQUE_KEY_ID=key1 SIGNING_PRIVATE_KEY=<YOUR_PRIVATE_KEY> SIGNING_PUBLIC_KEY=<YOUR_PUBLIC_KEY> # URLs BAP_URI=https://<YOUR_NGROK_URL> # Must be public! BPP_URI=https://gateway.nammayatri.in/search # Or local mock PORT=3000 -
Register: Use your BAP ID and Public Key to register on the Namma Yatri / Beckn Registry.
Usage
-
Start the Server:
npm run dev -
Connect via Ngrok (if running locally):
ngrok http 3000Update
BAP_URIin.envwith the ngrok URL. -
Connect your AI Client: Configure your MCP Client (e.g., Claude Desktop) to connect to the SSE endpoint:
- URL:
http://localhost:3000/sse
- URL:
Verification
We have included scripts to verify the system before going live:
-
Verify Crypto: Checks if your keys and signing logic are mathematically correct.
npx tsx src/verify_crypto.ts -
Verify Full Flow (Local): Runs a local Mock BPP and tests the full HTTP request/response loop.
npx tsx src/verify_full_flow.ts -
Black Box Test: Simulates an MCP Client connecting via SSE and calling tools.
npx tsx src/verify_mcp_client.ts
Project Structure
src/index.ts: Main server entry point (Hono app).src/tools/mobilityTools.ts: MCP Tool definitions (search_cabs, etc.).src/lib/becknClient.ts: Handles Beckn protocol communication and signing.src/lib/webhookManager.ts: Manages async callbacks.src/lib/honoTransport.ts: Custom MCP Transport for Hono.
License
MIT