Nigeria Invoices (FIRS / NRS MBS e-invoicing IRN)

Remote MCP server that lets any AI agent issue Nigeria e-invoices — validating, signing and confirming invoices through FIRS / NRS MBS (the NRS Merchant Buyer Solution e-invoicing platform). FIRS signs the invoice server-side and returns the IRN (Invoice Reference Number), CSID (Cryptographic Stamp Identifier) and QR code. Stateless, bring-your-own credentials, never stores anything.

Honest status. Each merchant enables e-invoicing on the NRS Merchant Buyer Solution and generates their own API key/secret in the NRSMBS Dashboard; this server is a pure forwarder (in-house / OEM path — not an APP/SI accreditation intermediary). The sandbox base URL is self-served from your Dashboard (send it via x-firs-base-url). This build is calibrated against the official FIRS MBS API surface and forwards correctly — fake-key probes reach the live gateway api.firsmbs.com and return its native error fingerprint — but no real end-to-end signing run has been made yet; the first real merchant with live credentials completes that verification. (Same honest posture as the India sister server.)

Live endpoint: https://inv-ng.wishpool.app/mcp · Registry: app.wishpool/nigeria-invoice-mcp

Quick start

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

Generate your API key and secret in your NRSMBS Dashboard → API Integration. Your business must first be enabled for e-invoicing on the NRS Merchant Buyer Solution. If your Dashboard issued a sandbox base URL, also send header x-firs-base-url (defaults to production https://api.firsmbs.com/api/v1).

Tools

Tool	What it does
validate_invoice	Pre-validate an invoice at FIRS / NRS MBS (POST /invoice/validate) before signing — returns pass, or the FIRS error list so you fix it before spending a submission.
create_invoice	Sign and submit the invoice (POST /invoice/sign). FIRS signs server-side and returns irn (IRN), csid (CSID) and qr_code.
query_invoice	Confirm a signed invoice by IRN (GET /invoice/confirm/{irn}) — transmission / delivery status.

You send flat fields (business_id, supplier/customer party_name + tin, invoice_number, service_id, line items with price); the server builds the UBL-mapped JSON and computes VAT.

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 (NGN).

IRN & VAT (computed for you)

• IRN = InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703). Pass irn directly, or let the server build it from invoice_number + service_id + issue_date.
• VAT at Nigeria's 7.5% standard rate (override per line with vat_rate; use 0 for exempt/zero-rated). The server groups tax_subtotal by rate under tax_category id VAT, and fills legal_monetary_total (line_extension_amount, tax_exclusive_amount, tax_inclusive_amount, payable_amount).

Example: one line of ₦1000 × 2 @ 7.5% → net ₦2000, VAT ₦150, payable ₦2150.

Develop

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

Safety

Pure stateless translation layer. FIRS / NRS MBS carries the validation and signing; the merchant's e-invoicing enablement and API credentials stay in the merchant's own NRSMBS account. Credentials travel per-request in headers, nothing is stored. Privacy policy.

Sister servers

Mexico CFDI 4.0 e-invoices (inv-mx.wishpool.app) and India GST e-invoices / IRN (inv-in.wishpool.app) are live. 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.