mcp-einvoicing-in 🇮🇳

English | हिन्दी

A Python MCP server providing tools for Indian GST e-invoicing, per GSTN's FORM GST INV-01 schema v1.1 (CGST Act 2017 s.31 + CGST Rule 48(4), Notification No. 68/2019-Central Tax). It enables AI agents (Claude, IDEs) to build and structurally validate GST e-invoice JSON payloads (INV, CRN, DBN document types) and render an IRP-returned signed QR string as a displayable image.

Phase A scope. This package covers offline payload building, structural validation, and GSTIN tax-identifier validation only. It does not submit to the Invoice Registration Portal (IRP) — live submission (auth/token, generate-IRN, cancel-IRN) is a later phase, blocked on the NIC e-invoice API specification not yet being available to this project (see "Spec availability" below). See Available tools for exactly what is implemented today.

Introduction

This package is built on mcp-einvoicing-core, the shared base library for e-invoicing MCP servers. It provides the InvoiceDocument model base and the TaxIdentifier.validate_in_gstin GSTIN validator.

mcp-einvoicing-core is installed automatically as a dependency, no additional step is required.

GST e-invoicing is a clearance-model system: an invoice becomes legally valid only once the IRP (Invoice Registration Portal, operated by NIC) validates the supplier's JSON payload and returns an Invoice Reference Number (IRN), acknowledgement number/date, and a signed QR code (CGST Rule 48(4)/(5)). This package builds and structurally validates the request payload a supplier would submit; it does not itself submit to the IRP (see "Phase A scope" above).

Installation

Via PyPI (recommended)

pip install mcp-einvoicing-in

Or without prior installation using uvx:

uvx mcp-einvoicing-in

From source

git clone https://github.com/cmendezs/mcp-einvoicing-in.git
cd mcp-einvoicing-in
pip install -e ".[dev]"

Configuration

This package requires no environment variables for its current (Phase A) scope — it performs no network calls. Live IRP submission, once implemented, will require IRP/GSP credentials; this section will be updated at that time.

Claude Desktop integration

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "einvoicing-in": {
      "command": "uvx",
      "args": ["mcp-einvoicing-in"]
    }
  }
}

Cursor integration

Add the same mcpServers block to either:

• Global: ~/.cursor/mcp.json
• Project-specific: .cursor/mcp.json in your project root

{
  "mcpServers": {
    "einvoicing-in": {
      "command": "uvx",
      "args": ["mcp-einvoicing-in"]
    }
  }
}

Reload Cursor (or run "Reload Window" from the command palette) after saving.

Kiro integration

Add to either:

• Global: ~/.kiro/settings/mcp.json
• Workspace: .kiro/settings/mcp.json

{
  "mcpServers": {
    "einvoicing-in": {
      "command": "uvx",
      "args": ["mcp-einvoicing-in"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Kiro reloads MCP configuration automatically on save. If a future version of this package requires credentials, prefer "VAR_NAME": "${VAR_NAME}" shell-interpolation syntax over plaintext secrets in this file.

Available tools

Scope

• in__get_supported_scope — returns the document types, supply types, and explicit out-of-scope items this package currently supports.

Build and validate

• in__build_invoice — validates structured input against INInvoice and builds a GST e-invoice JSON payload (INV/CRN/DBN). Never emits IRN — that field is IRP-generated, never supplier-populated.
• in__validate_invoice — offline structural/business-rule validation: mandatory fields, enum membership, CGST+SGST-vs-IGST pairing (item and document-total level), and GSTIN/state-code consistency. There is no XSD/Schematron pass — FORM GST INV-01 is JSON, not XML.

QR

• in__render_irp_qr_png — renders an IRP-returned signed QR string as a displayable PNG. Does not decode or interpret the QR's content — the NIC e-invoice API spec that would document that content is not yet available to this project (see "Spec availability" below).

Spec availability

Retrieving current, exact NIC/GSTN technical specifications from outside India is unreliable: the GSTN enforces strict geographic firewalls that routinely block or rate-limit non-Indian IP addresses. This package was built entirely from specification documents supplied directly by the maintainer (FORM GST INV-01 schema v1.1, and CGST Notifications 68/2019-CT and 72/2020-CT) — no document was fetched from the internet by an automated agent. As a direct consequence:

• Not yet available to this project: the current AATO mandate-threshold notification (Notification No. 10/2023-Central Tax), the NIC e-invoice API specification (authentication, generate-IRN, cancel-IRN, signed-QR content), and the master code lists (state codes, HSN, UQC, currency, port codes).
• Live IRP submission tools cannot be built responsibly without the API spec above — see "Phase A scope".

If you are based in India and can supply any of the documents above, please open an issue using the Spec Update issue template. The template captures the document name, official source URL, version, and retrieval date; a follow-up pull request then adds the file under specs/ together with a sources-table entry and a provenance/redistribution affirmation. See CONTRIBUTING.md for the full two-step flow.

Architecture

INInvoice subclasses InvoiceDocument (mcp_einvoicing_core.models) — FORM GST INV-01 has no EN 16931/UBL/CII lineage (it is a flat JSON clearance-model schema), so this package follows the InvoiceDocument pathway, the same one used by mcp-cfdi-mx (CFDI) and mcp-nfe-br (NF-e). INInvoiceLine subclasses InvoiceLineItem to add the schema's GST/HSN/cess fields, which have no equivalent in the base line-item model. GSTIN fields are validated via TaxIdentifier.validate_in_gstin, called from INInvoice's own model validators — this package never reimplements identifier-validation logic locally. There is no Schematron/XSD validator layer (validators/structural.py implements plain-Python business-rule checks instead), since the wire format is JSON, not XML.

Contributing

See CONTRIBUTING.md for development setup, the PR checklist, and commit style.

Other e-invoicing MCP servers

License

This project is licensed under the Apache 2.0 license — see LICENSE for details. For the full version history, see CHANGELOG.md.