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

Official3 toolsLive

by junter1989k-ai · JavaScript

Nigeria FIRS/NRS MBS e-invoicing for AI agents - validate, sign, confirm invoices (IRN + QR).

Topics

ai-agentclaudee-invoicefirsinvoiceirnmcpmcp-servernigeriataxvatwishpoolzatca

Captured live from the server via tools/list.

validate_invoice

Pre-validate a Nigeria e-invoice against FIRS / NRS MBS (Merchant Buyer Solution) BEFORE signing — POST /invoice/validate. Returns pass, or the FIRS error list if the payload is rejected (so you fix it before spending a real submission). Bring your own credentials via headers x-firs-api-key AND x-firs-api-secret (generate them in your NRSMBS Dashboard -> API Integration; your business must be enabled for e-invoicing first). If your Dashboard issued a sandbox base URL, also send header x-firs-base-url. You send flat fields (business_id, supplier/customer party name + TIN, invoice_number, service_id, line items with price); this server builds the UBL-mapped JSON and computes VAT (7.5% default) into tax_total and legal_monetary_total. No fiscal effect — nothing is signed.

Parameters21

business_id	string	required	Your FIRS business_id (UUID) from your NRSMBS Dashboard — identifies the taxpayer entity submitting the invoice.
invoice_number	string	optional	Your own invoice/document number (used to build the IRN, unless you pass irn directly). E.g. INV001.
service_id	string	optional	Your FIRS-issued Service ID (the middle segment of the IRN, e.g. 6997D6BB). Used with invoice_number + issue_date to build the IRN. Not needed if you pass irn directly.
irn	string	optional	Optional ready-made IRN, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703). If omitted, built from invoice_number + service_id + issue_date.
issue_date	string	optional	Invoice date YYYY-MM-DD. Defaults to today (UTC).
invoice_type_code	string	optional	FIRS invoice type code. Default 396 (commercial invoice). See the MBS GetInvoiceTypes list for others.
document_currency_code	string	optional	ISO currency of the invoice. Default NGN.
supplier_name	string	required	Seller (supplier) legal party_name as registered with FIRS.
supplier_tin	string	required	Seller Tax Identification Number (TIN), e.g. TIN-0099990001.
supplier_email	string	optional	Optional seller email.
supplier_street	string	optional	Optional seller street_name (postal_address).
supplier_city	string	optional	Optional seller city_name.
supplier_postal_zone	string	optional	Optional seller postal_zone (post code).
customer_name	string	required	Buyer (customer) legal party_name.
customer_tin	string	required	Buyer Tax Identification Number (TIN).
customer_email	string	optional	Optional buyer email.
customer_street	string	optional	Optional buyer street_name (postal_address).
customer_city	string	optional	Optional buyer city_name.
customer_postal_zone	string	optional	Optional buyer postal_zone (post code).
tax_category_id	string	optional	Optional FIRS tax_category id for the VAT lines. Default VAT (value-added tax). Use another MBS tax-category code only if the goods fall under a different regime.
items	array	required	Line items. Each: name, price (unit price in NGN, tax-EXCLUSIVE), optional quantity (default 1), vat_rate (percent, default 7.5), hsn_code, description, product_category. VAT is computed on top of price*quantity.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Your FIRS business_id (UUID) from your NRSMBS Dashboard — identifies the taxpayer entity submitting the invoice."
    },
    "invoice_number": {
      "type": "string",
      "description": "Your own invoice/document number (used to build the IRN, unless you pass irn directly). E.g. INV001."
    },
    "service_id": {
      "type": "string",
      "description": "Your FIRS-issued Service ID (the middle segment of the IRN, e.g. 6997D6BB). Used with invoice_number + issue_date to build the IRN. Not needed if you pass irn directly."
    },
    "irn": {
      "type": "string",
      "description": "Optional ready-made IRN, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703). If omitted, built from invoice_number + service_id + issue_date."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice date YYYY-MM-DD. Defaults to today (UTC)."
    },
    "invoice_type_code": {
      "type": "string",
      "description": "FIRS invoice type code. Default 396 (commercial invoice). See the MBS GetInvoiceTypes list for others."
    },
    "document_currency_code": {
      "type": "string",
      "description": "ISO currency of the invoice. Default NGN."
    },
    "supplier_name": {
      "type": "string",
      "description": "Seller (supplier) legal party_name as registered with FIRS."
    },
    "supplier_tin": {
      "type": "string",
      "description": "Seller Tax Identification Number (TIN), e.g. TIN-0099990001."
    },
    "supplier_email": {
      "type": "string",
      "description": "Optional seller email."
    },
    "supplier_street": {
      "type": "string",
      "description": "Optional seller street_name (postal_address)."
    },
    "supplier_city": {
      "type": "string",
      "description": "Optional seller city_name."
    },
    "supplier_postal_zone": {
      "type": "string",
      "description": "Optional seller postal_zone (post code)."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer (customer) legal party_name."
    },
    "customer_tin": {
      "type": "string",
      "description": "Buyer Tax Identification Number (TIN)."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email."
    },
    "customer_street": {
      "type": "string",
      "description": "Optional buyer street_name (postal_address)."
    },
    "customer_city": {
      "type": "string",
      "description": "Optional buyer city_name."
    },
    "customer_postal_zone": {
      "type": "string",
      "description": "Optional buyer postal_zone (post code)."
    },
    "tax_category_id": {
      "type": "string",
      "description": "Optional FIRS tax_category id for the VAT lines. Default VAT (value-added tax). Use another MBS tax-category code only if the goods fall under a different regime."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each: name, price (unit price in NGN, tax-EXCLUSIVE), optional quantity (default 1), vat_rate (percent, default 7.5), hsn_code, description, product_category. VAT is computed on top of price*quantity.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "Tax-exclusive unit price in NGN."
          },
          "quantity": {
            "type": "number",
            "description": "Default 1."
          },
          "vat_rate": {
            "type": "number",
            "description": "VAT percent for this line. Default 7.5 (Nigeria standard rate). Use 0 for exempt/zero-rated."
          },
          "hsn_code": {
            "type": "string",
            "description": "Optional product/commodity code."
          },
          "product_category": {
            "type": "string",
            "description": "Optional product category."
          }
        },
        "required": [
          "name",
          "price"
        ]
      }
    }
  },
  "required": [
    "business_id",
    "supplier_name",
    "supplier_tin",
    "customer_name",
    "customer_tin",
    "items"
  ]
}

create_invoice

Sign and submit a Nigeria e-invoice to FIRS / NRS MBS — POST /invoice/sign. FIRS signs it server-side and returns the official IRN (Invoice Reference Number), CSID (Cryptographic Stamp Identifier) and QR code to print on the invoice. Bring your own credentials via headers x-firs-api-key AND x-firs-api-secret. The IRN format is InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703): pass irn directly if you already have it, otherwise this server builds it from invoice_number + service_id + issue_date. You send flat fields; the server builds the UBL-mapped JSON and computes VAT (7.5% Nigeria standard rate by default; override per line with vat_rate) into tax_total and legal_monetary_total. Recommended: call validate_invoice first.

Parameters21

business_id	string	required	Your FIRS business_id (UUID) from your NRSMBS Dashboard — identifies the taxpayer entity submitting the invoice.
invoice_number	string	optional	Your own invoice/document number (used to build the IRN, unless you pass irn directly). E.g. INV001.
service_id	string	optional	Your FIRS-issued Service ID (the middle segment of the IRN, e.g. 6997D6BB). Used with invoice_number + issue_date to build the IRN. Not needed if you pass irn directly.
irn	string	optional	Optional ready-made IRN, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703). If omitted, built from invoice_number + service_id + issue_date.
issue_date	string	optional	Invoice date YYYY-MM-DD. Defaults to today (UTC).
invoice_type_code	string	optional	FIRS invoice type code. Default 396 (commercial invoice). See the MBS GetInvoiceTypes list for others.
document_currency_code	string	optional	ISO currency of the invoice. Default NGN.
supplier_name	string	required	Seller (supplier) legal party_name as registered with FIRS.
supplier_tin	string	required	Seller Tax Identification Number (TIN), e.g. TIN-0099990001.
supplier_email	string	optional	Optional seller email.
supplier_street	string	optional	Optional seller street_name (postal_address).
supplier_city	string	optional	Optional seller city_name.
supplier_postal_zone	string	optional	Optional seller postal_zone (post code).
customer_name	string	required	Buyer (customer) legal party_name.
customer_tin	string	required	Buyer Tax Identification Number (TIN).
customer_email	string	optional	Optional buyer email.
customer_street	string	optional	Optional buyer street_name (postal_address).
customer_city	string	optional	Optional buyer city_name.
customer_postal_zone	string	optional	Optional buyer postal_zone (post code).
tax_category_id	string	optional	Optional FIRS tax_category id for the VAT lines. Default VAT (value-added tax). Use another MBS tax-category code only if the goods fall under a different regime.
items	array	required	Line items. Each: name, price (unit price in NGN, tax-EXCLUSIVE), optional quantity (default 1), vat_rate (percent, default 7.5), hsn_code, description, product_category. VAT is computed on top of price*quantity.

Raw schema

{
  "type": "object",
  "properties": {
    "business_id": {
      "type": "string",
      "description": "Your FIRS business_id (UUID) from your NRSMBS Dashboard — identifies the taxpayer entity submitting the invoice."
    },
    "invoice_number": {
      "type": "string",
      "description": "Your own invoice/document number (used to build the IRN, unless you pass irn directly). E.g. INV001."
    },
    "service_id": {
      "type": "string",
      "description": "Your FIRS-issued Service ID (the middle segment of the IRN, e.g. 6997D6BB). Used with invoice_number + issue_date to build the IRN. Not needed if you pass irn directly."
    },
    "irn": {
      "type": "string",
      "description": "Optional ready-made IRN, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703). If omitted, built from invoice_number + service_id + issue_date."
    },
    "issue_date": {
      "type": "string",
      "description": "Invoice date YYYY-MM-DD. Defaults to today (UTC)."
    },
    "invoice_type_code": {
      "type": "string",
      "description": "FIRS invoice type code. Default 396 (commercial invoice). See the MBS GetInvoiceTypes list for others."
    },
    "document_currency_code": {
      "type": "string",
      "description": "ISO currency of the invoice. Default NGN."
    },
    "supplier_name": {
      "type": "string",
      "description": "Seller (supplier) legal party_name as registered with FIRS."
    },
    "supplier_tin": {
      "type": "string",
      "description": "Seller Tax Identification Number (TIN), e.g. TIN-0099990001."
    },
    "supplier_email": {
      "type": "string",
      "description": "Optional seller email."
    },
    "supplier_street": {
      "type": "string",
      "description": "Optional seller street_name (postal_address)."
    },
    "supplier_city": {
      "type": "string",
      "description": "Optional seller city_name."
    },
    "supplier_postal_zone": {
      "type": "string",
      "description": "Optional seller postal_zone (post code)."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer (customer) legal party_name."
    },
    "customer_tin": {
      "type": "string",
      "description": "Buyer Tax Identification Number (TIN)."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email."
    },
    "customer_street": {
      "type": "string",
      "description": "Optional buyer street_name (postal_address)."
    },
    "customer_city": {
      "type": "string",
      "description": "Optional buyer city_name."
    },
    "customer_postal_zone": {
      "type": "string",
      "description": "Optional buyer postal_zone (post code)."
    },
    "tax_category_id": {
      "type": "string",
      "description": "Optional FIRS tax_category id for the VAT lines. Default VAT (value-added tax). Use another MBS tax-category code only if the goods fall under a different regime."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "description": "Line items. Each: name, price (unit price in NGN, tax-EXCLUSIVE), optional quantity (default 1), vat_rate (percent, default 7.5), hsn_code, description, product_category. VAT is computed on top of price*quantity.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "Tax-exclusive unit price in NGN."
          },
          "quantity": {
            "type": "number",
            "description": "Default 1."
          },
          "vat_rate": {
            "type": "number",
            "description": "VAT percent for this line. Default 7.5 (Nigeria standard rate). Use 0 for exempt/zero-rated."
          },
          "hsn_code": {
            "type": "string",
            "description": "Optional product/commodity code."
          },
          "product_category": {
            "type": "string",
            "description": "Optional product category."
          }
        },
        "required": [
          "name",
          "price"
        ]
      }
    }
  },
  "required": [
    "business_id",
    "supplier_name",
    "supplier_tin",
    "customer_name",
    "customer_tin",
    "items"
  ]
}

query_invoice

Look up a signed Nigeria e-invoice by its IRN at FIRS / NRS MBS — GET /invoice/confirm/{irn}. Returns the transmission / delivery status and the IRN/CSID. Safe to call anytime.

Parameters1

irn

string

required

The IRN returned by create_invoice, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703).

Raw schema

{
  "type": "object",
  "properties": {
    "irn": {
      "type": "string",
      "description": "The IRN returned by create_invoice, format InvoiceNumber-ServiceID-YYYYMMDD (e.g. ITW20853450-6997D6BB-20240703)."
    }
  },
  "required": [
    "irn"
  ]
}

README.md4 KBView on GitHub

Nigeria Invoice MCP 🇳🇬 — How can my AI agent issue a FIRS e-invoice (IRN) in Nigeria?

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

json

{
  "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

bash

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.

Install

Tools (3)

validate_invoicecreate_invoicequery_invoice

Remote endpoint

Streamable HTTP

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

url

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

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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