bluedart-mcp-server

Model Context Protocol (MCP) server for the BlueDart (DHL eCommerce India) shipping API.

Exposes BlueDart's APIGEE endpoints — waybill creation, cancellation, pickup scheduling, transit-time lookup, tracking, and master downloads — as MCP tools that can be used by Claude Desktop, Claude Code, ChatGPT, and other standard MCP clients.

Tools

Tool	Method	What it does
bluedart_generate_waybill	write	Create a single AWB (POST /waybill/v1/GenerateWayBill)
bluedart_import_waybill	write	Bulk-create AWBs (POST /waybill/v1/ImportData)
bluedart_cancel_waybill	write	Cancel an AWB before in-scan
bluedart_register_pickup	write	Schedule a pickup
bluedart_cancel_pickup	write	Cancel a registered pickup
bluedart_get_transit_time	read	Estimate delivery date between two pincodes
bluedart_track_shipment	read	Track a shipment by AWB (markdown or json)
bluedart_download_pincode_master	read	Download serviceable pincode master

All tools return both a text and a structuredContent payload, with BlueDart's error fields (Status[].StatusInformation, IsError, etc.) surfaced into a normalised error field.

Setup

npm install
cp .env.example .env       # fill in your BlueDart APIGEE credentials
npm run build

Environment variables

Var	Required	Description
BLUEDART_BASE_URL	yes	https://apigateway-sandbox.bluedart.com/in/transportation (sandbox) or https://apigateway.bluedart.com/in/transportation (prod)
BLUEDART_CLIENT_ID	yes	OAuth Consumer Key from your APIGEE app
BLUEDART_CLIENT_SECRET	yes	OAuth Consumer Secret
BLUEDART_LOGIN_ID	yes	Profile LoginID (used in BlueDart payload)
BLUEDART_LICENSE_KEY	yes	Profile LicenceKey
BLUEDART_API_TYPE	no	S (sandbox) or as documented (default: S)
BLUEDART_DEBUG	no	true for verbose stderr logging

JWT tokens are fetched once from /token/v1/login and cached in memory; the server auto-refreshes when the token is within 30 seconds of expiry, and will retry once on a 401/403.

Client configuration

Claude Desktop / Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "bluedart": {
      "command": "node",
      "args": ["/absolute/path/to/bluedart-mcp-server/dist/index.js"],
      "env": {
        "BLUEDART_BASE_URL": "https://apigateway-sandbox.bluedart.com/in/transportation",
        "BLUEDART_CLIENT_ID": "...",
        "BLUEDART_CLIENT_SECRET": "...",
        "BLUEDART_LOGIN_ID": "...",
        "BLUEDART_LICENSE_KEY": "...",
        "BLUEDART_API_TYPE": "S"
      }
    }
  }
}

ChatGPT

Configure as a stdio MCP server with the same node dist/index.js command and environment variables.

Notes & caveats

• OriginArea must match the shipper pincode region. A mismatch returns InvalidAreaScNotInRegion. Example: OriginArea='DEL' with pincode 110030.
• CreditReferenceNo must be unique per shipment. Reuse triggers Waybill already generated.
• Weight is in kilograms; dimensions in centimetres.
• The label PDF (AWBPrintContent) is base64-encoded and can be very large — set PDFOutputNotRequired: true in Services if you don't need it.
• This server only does API I/O. Custom label rendering (e.g. with logos/barcodes) is intentionally out of scope — do that in your application layer.

Development

npm run dev      # tsx watch mode
npm run build    # compile to dist/
npm start        # run built server (stdio)

License

MIT