India Invoices (GST e-invoicing IRN via IRP)

Official3 toolsLive

by junter1989k-ai · JavaScript

India GST e-invoicing for AI agents - generate, query, cancel IRNs at the IRP via a GSP. Stateless.

Topics

ai-agentse-invoicegstindiainvoicingirnmcpmcp-serverai-agentclaudeinvoicetaxwishpool

Captured live from the server via tools/list.

create_invoice

Generate a GST e-invoice and get an IRN (Invoice Reference Number) from the IRP (Invoice Registration Portal, run by GSTN), stamped through the Sandbox.co.in GSP. Bring your own Sandbox credentials via headers x-sandbox-api-key AND x-sandbox-api-secret (sign up at sandbox.co.in). Your GSTIN must already have GST e-Invoice API access enabled on the e-Invoice portal and mapped to Sandbox as your GSP. e-Invoicing is B2B only — BOTH seller and buyer must have valid 15-char GSTINs. Give flat fields (seller/buyer GSTIN + name + address, doc_number, line items with hsn_code, price, quantity, gst_rate) and this server COMPUTES the INV-01 tax schema for you: taxable value per line, CGST+SGST split for same-state supply vs IGST for cross-state supply (decided automatically from the seller GSTIN state vs the place-of-supply state), item totals, and the invoice totals (AssVal / TotInvVal). Returns Irn, AckNo, AckDt and SignedQRCode.

Parameters14

seller_gstin	string	required	Seller (supplier) 15-char GSTIN, e.g. 29ABCDE1234F1Z5. Its first 2 digits are the seller state code and drive the CGST+SGST vs IGST decision.
seller_legal_name	string	required	Seller legal name (LglNm) exactly as registered under this GSTIN.
seller_address	string	required	Seller registered address line 1 (Addr1).
seller_city	string	required	Seller city / location (Loc).
seller_pincode	string	required	Seller 6-digit PIN code (Pin).
buyer_gstin	string	required	Buyer (recipient) 15-char GSTIN. Required — e-invoicing is B2B only.
buyer_legal_name	string	required	Buyer legal name (LglNm) as registered under the buyer GSTIN.
buyer_address	string	required	Buyer address line 1 (Addr1).
buyer_city	string	required	Buyer city / location (Loc).
buyer_pincode	string	required	Buyer 6-digit PIN code (Pin).
buyer_state_code	string	optional	Optional place-of-supply state code (POS), 2 digits. Defaults to the buyer GSTIN state code. Set this if the place of supply differs from the buyer registration state.
doc_number	string	required	Your invoice/document number (DocDtls.No), max 16 chars.
doc_date	string	optional	Invoice date DD/MM/YYYY (DocDtls.Dt). Defaults to today (UTC).
items	array	required	Line items. Each: description, hsn_code (HSN/SAC), price (unit price in INR, tax-EXCLUSIVE), gst_rate (percent, e.g. 18), optional quantity (default 1) and unit (default NOS). GST is computed on top of price*quantity.

Raw schema

{
  "type": "object",
  "properties": {
    "seller_gstin": {
      "type": "string",
      "description": "Seller (supplier) 15-char GSTIN, e.g. 29ABCDE1234F1Z5. Its first 2 digits are the seller state code and drive the CGST+SGST vs IGST decision."
    },
    "seller_legal_name": {
      "type": "string",
      "description": "Seller legal name (LglNm) exactly as registered under this GSTIN."
    },
    "seller_address": {
      "type": "string",
      "description": "Seller registered address line 1 (Addr1)."
    },
    "seller_city": {
      "type": "string",
      "description": "Seller city / location (Loc)."
    },
    "seller_pincode": {
      "type": "string",
      "description": "Seller 6-digit PIN code (Pin)."
    },
    "buyer_gstin": {
      "type": "string",
      "description": "Buyer (recipient) 15-char GSTIN. Required — e-invoicing is B2B only."
    },
    "buyer_legal_name": {
      "type": "string",
      "description": "Buyer legal name (LglNm) as registered under the buyer GSTIN."
    },
    "buyer_address": {
      "type": "string",
      "description": "Buyer address line 1 (Addr1)."
    },
    "buyer_city": {
      "type": "string",
      "description": "Buyer city / location (Loc)."
    },
    "buyer_pincode": {
      "type": "string",
      "description": "Buyer 6-digit PIN code (Pin)."
    },
    "buyer_state_code": {
      "type": "string",
      "description": "Optional place-of-supply state code (POS), 2 digits. Defaults to the buyer GSTIN state code. Set this if the place of supply differs from the buyer registration state."
    },
    "doc_number": {
      "type": "string",
      "description": "Your invoice/document number (DocDtls.No), max 16 chars."
    },
    "doc_date": {
      "type": "string",
      "description": "Invoice date DD/MM/YYYY (DocDtls.Dt). Defaults to today (UTC)."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each: description, hsn_code (HSN/SAC), price (unit price in INR, tax-EXCLUSIVE), gst_rate (percent, e.g. 18), optional quantity (default 1) and unit (default NOS). GST is computed on top of price*quantity.",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "hsn_code": {
            "type": "string",
            "description": "HSN (goods) or SAC (services) code."
          },
          "price": {
            "type": "number",
            "description": "Tax-exclusive unit price in INR."
          },
          "quantity": {
            "type": "number",
            "description": "Default 1."
          },
          "gst_rate": {
            "type": "number",
            "description": "GST rate percent, e.g. 0, 5, 12, 18, 28."
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure (UQC), default NOS."
          }
        },
        "required": [
          "description",
          "hsn_code",
          "price",
          "gst_rate"
        ]
      }
    }
  },
  "required": [
    "seller_gstin",
    "seller_legal_name",
    "seller_address",
    "seller_city",
    "seller_pincode",
    "buyer_gstin",
    "buyer_legal_name",
    "buyer_address",
    "buyer_city",
    "buyer_pincode",
    "doc_number",
    "items"
  ]
}

query_invoice

Look up a GST e-invoice by its IRN at the IRP. Status values: ACT (active / valid) or CNL (cancelled). Safe to call anytime.

Parameters1

irn

string

required

The 64-char IRN returned by create_invoice.

Raw schema

{
  "type": "object",
  "properties": {
    "irn": {
      "type": "string",
      "description": "The 64-char IRN returned by create_invoice."
    }
  },
  "required": [
    "irn"
  ]
}

cancel_invoice

Cancel a GST e-invoice at the IRP. IMPORTANT: the IRP only allows cancellation WITHIN 24 HOURS of IRN generation (and only if no e-way bill is active / it was not already cancelled) — after 24h you must instead issue a credit note. A reason code is required: 1 Duplicate, 2 Data entry mistake, 3 Order cancelled, 4 Others (default 4). Remarks are required by the IRP.

Parameters3

irn	string	required	The IRN returned by create_invoice.
reason_code	string	optional	NIC cancellation reason: 1 Duplicate, 2 Data entry mistake, 3 Order cancelled, 4 Others. Default 4.
remarks	string	optional	Free-text remarks explaining the cancellation (required by the IRP), max 100 chars.

Raw schema

{
  "type": "object",
  "properties": {
    "irn": {
      "type": "string",
      "description": "The IRN returned by create_invoice."
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "1",
        "2",
        "3",
        "4"
      ],
      "description": "NIC cancellation reason: 1 Duplicate, 2 Data entry mistake, 3 Order cancelled, 4 Others. Default 4."
    },
    "remarks": {
      "type": "string",
      "description": "Free-text remarks explaining the cancellation (required by the IRP), max 100 chars."
    }
  },
  "required": [
    "irn"
  ]
}

README.md4 KBView on GitHub

India Invoice MCP 🇮🇳 — How can my AI agent generate a GST e-invoice (IRN) in India?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "india-invoice": {
      "type": "http",
      "url": "https://inv-in.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/india-invoice-mcp && cd india-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent generate India GST e-invoices — registering an invoice with the IRP (Invoice Registration Portal, run by GSTN) to get an IRN (Invoice Reference Number) plus the signed QR code — through the Sandbox.co.in GSP (GST Suvidha Provider). Stateless, bring-your-own credentials, never stores anything.

Live endpoint: https://inv-in.wishpool.app/mcp · Registry: app.wishpool/india-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "india-invoice": {
      "type": "http",
      "url": "https://inv-in.wishpool.app/mcp",
      "headers": {
        "x-sandbox-api-key": "your-key",
        "x-sandbox-api-secret": "your-secret"
      }
    }
  }
}

Sign up at sandbox.co.in for GSP credentials. Your GSTIN must have GST e-Invoice API access enabled on the e-Invoice portal and mapped to Sandbox as your GSP — otherwise the IRP rejects the stamp. e-Invoicing is B2B only: both seller and buyer need valid GSTINs.

Tools

Tool	What it does
`create_invoice`	Register a GST e-invoice at the IRP and get the `irn` (+ `AckNo`, `AckDt`, `SignedQRCode`). You send flat fields (GSTINs, names, addresses, line items with HSN + price + gst_rate); the server auto-computes the INV-01 tax schema — taxable value, CGST+SGST split for same-state supply vs IGST for cross-state, item + invoice totals.
`query_invoice`	Status check by IRN: `ACT` (active) or `CNL` (cancelled).
`cancel_invoice`	Cancel at the IRP with a reason code (`1`–`4`, default `4`) — only within 24 hours of generation; after that, issue a credit note.

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them. The amount cap/threshold applies to the invoice total (INR).

GST tax split (computed for you)

The place of supply (POS) state code is compared with the seller GSTIN's state code:

Same state → intra-state supply → CGST + SGST, each at half the GST rate.
Different state → inter-state supply → IGST at the full GST rate.

Example: seller in state 29, buyer in state 29, one line of ₹1000 × 2 @ 18% → AssVal ₹2000, CGST ₹180 + SGST ₹180, TotInvVal ₹2360. Same line to a buyer in state 27 → IGST ₹360, TotInvVal ₹2360.

Develop

bash

node test/serve.js   # local server on :3230
node test/e2e.js     # protocol + validation + GST math unit check + fake-key live probe

Safety

Pure stateless translation layer. The IRP/GSTN certification burden sits with the Sandbox.co.in GSP; credentials travel per-request in headers, nothing is stored. Privacy policy.

Sister servers

Mexico CFDI 4.0 e-invoices are live: inv-mx.wishpool.app. Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included. More invoice countries coming: Brazil NF-e · Chile DTE · Peru CPE · Poland KSeF · Romania e-Factura · Italy SdI.

MIT licensed.

Install

Tools (3)

create_invoicequery_invoicecancel_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-in.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "india-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-in.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.