gst-einvoice-mcp
This server provides MCP tools for parsing Indian GST invoices into INV-01 JSON payloads and validating GST-related data.\n\n- parse_invoice: Extracts structured INV-01 payload from a PDF or image invoice, including per-field provenance, warnings, missing fields, and refusals for out-of-scope documents (export/SEZ/foreign-currency).\n- validate_gstin: Checks a GSTIN's structural validity, mod-36 checksum, state code, and PAN, with special handling for discontinued and legacy codes.\n- validate_payload: Runs four arithmetic and tax-split consistency checks on an existing INV-01 payload, with configurable rupee tolerance and schema validation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gst-einvoice-mcp Convert this GST invoice to INV-01 JSON: ~/Downloads/tax-invoice.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GST e-invoice extraction
Turns an Indian GST tax invoice into the government's INV-01 JSON payload, and tells you exactly what it could not read.
Ships as an MCP server with three tools, so an agent can parse a document, check a GSTIN, or re-validate a payload it already holds.
It produces a submission-ready payload, not a filed invoice. There is no IRN here. An Invoice Reference Number is issued by the government's Invoice Registration Portal after you submit the payload to it. Nothing in this repository talks to the IRP.
The idea
An extraction tool that quietly guesses is worse than one that says it cannot read a field. A hallucinated digit in a GSTIN that still passes its checksum, or a line item that was never on the page, is the failure that costs an accountant real money — and it is invisible precisely because it looks right.
So the design has one rule: the model may structure text, it may never invent values. That is enforced twice. The prompt says it, and then every value the model returns is checked back against the document text before it is kept. A value with no source in the document is replaced with null and reported, however plausible it looks. If that field is mandatory in INV-01, no payload is produced at all.
Everything the tool knows about its own work — how each page was read, where each field came from, what it was unsure about — travels beside the payload in extraction_meta, never inside it. The payload stays strictly spec-pure, because the government API rejects unknown keys.
Read LIMITATIONS.md before trusting the output. It is specific about what the tool cannot corroborate, and what that costs you.
Related MCP server: mcp-einvoicing-in
Install
Requires Python 3.11 or newer and Tesseract OCR as a system dependency.
# Tesseract (Windows)
winget install UB-Mannheim.TesseractOCR
# Tesseract (Debian/Ubuntu)
sudo apt-get install -y tesseract-ocr
# Tesseract (macOS)
brew install tesseract# From PyPI -- installs the `gst-einvoice-mcp` command the MCP client configuration below names
pip install gst-einvoice-mcp
# Or from a clone, for development (editable)
python -m venv .venv
.venv/Scripts/activate # Windows
# source .venv/bin/activate # Linux / macOS
pip install -e .Tesseract does not need to be on PATH: the OCR module looks there first, then at the standard Windows install location, and raises an actionable error naming both if neither works.
Environment
Variable | Required | Purpose |
| yes | Stage 2 reads the line-item table through Groq |
| recommended | Pin the model your key can reach |
| no |
|
The default model is openai/gpt-oss-120b, which is what this release was validated against. It works without configuration.
Still set
GST_MCP_MODELin a deployment. A hard-coded model identifier expires silently when the provider retires it, and the failure arrives as an HTTP 404 that reads like a bad key rather than a stale constant. Pin the model you have access to, and check it against Groq's deprecation notices.
MCP client configuration
pip install puts a gst-einvoice-mcp command on your PATH, so a client only needs to name it:
{
"mcpServers": {
"gst-einvoice": {
"command": "gst-einvoice-mcp",
"env": {
"GROQ_API_KEY": "your-key-here",
"GST_MCP_MODEL": "openai/gpt-oss-120b"
}
}
}
}Running from a clone rather than an install? Point command at the interpreter inside your virtual environment and invoke the module directly:
{
"mcpServers": {
"gst-einvoice": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["-m", "gst_einvoice.server"],
"env": {
"GROQ_API_KEY": "your-key-here"
}
}
}
}On Windows that interpreter path ends \.venv\Scripts\python.exe.
Tools
Tool | Takes | Gives back |
| a file path, optional tolerance | the INV-01 payload, missing fields, refusals, and |
| a GSTIN | structure, checksum, state code, PAN, and the reason on failure |
| an INV-01 payload | the four consistency checks over a payload you already hold |
parse_invoice has three normal outcomes, and only the first gives you a payload:
A payload plus warnings. Usable, but the warnings say which fields were read at low OCR confidence, which were assigned by position rather than by a label, and which were derived rather than printed.
No payload,
missing_fieldspopulated. A mandatory field could not be read. Nothing was invented to fill the gap, which is why there is no payload.No payload,
refusalspopulated. Export, SEZ and foreign-currency invoices are refused by design, with a message saying what was detected and what to do instead.
Worked example
The invoice, as a text-layer PDF:
TAX INVOICE
Seller: Nimbus Components Pvt Ltd
GSTIN 27AAPFU0939F1ZV
Plot 14 MIDC Andheri East
Mumbai 400093
Invoice No: INV-2026-0042
Invoice Date: 17/04/2026
Buyer: Kanchan Electricals LLP
GSTIN 27AABCB5507N1ZJ
221 Laxmi Road Shivajinagar
Pune 411005
Sl No 01 Laptop Stand
Qty 4 NOS Rate 1500.00
Taxable 6000.00 GST 18%
CGST 540.00 SGST 540.00 IGST 0.00
HSN/SAC: 8471
Goods once sold will not be taken back or exchanged
Total Invoice Value 7080.00from gst_einvoice.extract_llm import make_client
from gst_einvoice.pipeline import extract_invoice
# model defaults to openai/gpt-oss-120b; pass model=... to override
result = extract_invoice("sample_invoice.pdf", client=make_client())The payload
{
"Version": "1.1",
"TranDtls": { "TaxSch": "GST", "SupTyp": "B2B" },
"DocDtls": { "Typ": "INV", "No": "INV-2026-0042", "Dt": "17/04/2026" },
"SellerDtls": {
"Gstin": "27AAPFU0939F1ZV",
"LglNm": "Nimbus Components Pvt Ltd",
"Addr1": "Plot 14 MIDC Andheri East",
"Loc": "Mumbai",
"Pin": 400093,
"Stcd": "27"
},
"BuyerDtls": {
"Gstin": "27AABCB5507N1ZJ",
"LglNm": "Kanchan Electricals LLP",
"Addr1": "221 Laxmi Road Shivajinagar",
"Loc": "Pune",
"Pin": 411005,
"Stcd": "27",
"Pos": "27"
},
"ItemList": [
{
"SlNo": "01",
"PrdDesc": "Laptop Stand",
"IsServc": "N",
"HsnCd": "8471",
"Qty": 4.0,
"Unit": "NOS",
"UnitPrice": 1500.0,
"TotAmt": 6000.0,
"Discount": 0.0,
"AssAmt": 6000.0,
"GstRt": 18.0,
"CgstAmt": 540.0,
"SgstAmt": 540.0,
"IgstAmt": 0.0,
"CesAmt": 0.0,
"StateCesAmt": 0.0,
"OthChrg": 0.0,
"TotItemVal": 7080.0
}
],
"ValDtls": {
"AssVal": 6000.0, "CgstVal": 540.0, "SgstVal": 540.0, "IgstVal": 0.0,
"CesVal": 0.0, "StCesVal": 0.0, "RndOffAmt": 0.0, "TotInvVal": 7080.0
}
}The warnings block
This is the half most tools do not give you. Six entries, from the run above, all info:
[info] extract_llm ItemList[0].HsnCd
"8471" is not printed as a code of its own in this row's text: it was grounded by
the HSN/SAC codes stage 1 confirmed, or by a longer number elsewhere on the page.
Which code belongs to which row is therefore the model's judgement and could not
be corroborated against the document. A code on the wrong row changes that row's
tax classification, so confirm it against the invoice.
[info] extract_llm ItemList[0].Discount
ItemList[0].Discount was not found in the document: the model returned no value
for it, so it is left empty rather than filled with a guess.
[info] extract_llm ItemList[0].CesAmt (same wording)
[info] extract_llm ValDtls.CesVal (same wording)
[info] extract_llm ValDtls.RndOffAmt (same wording)
[info] pipeline BuyerDtls.Pos
BuyerDtls.Pos (place of supply) was not read from the document -- build 2 does
not extract it -- so it was assumed equal to the buyer's registered state code
(27). A genuine bill-to/ship-to supply, where the goods go to a different state
from the one the buyer is registered in, has a different place of supply, and
the CGST/SGST-versus-IGST split follows the place of supply. Confirm it against
the document before filing.Nothing in that list means the payload is wrong. Each one names something the tool could not corroborate, so you know where to look. The four arithmetic validators raised nothing, which is what silence from them means.
On an invoice whose template omits a column — an intra-state invoice with no IGST column, or one that prints a taxable value but no separate gross — you will also see a pipeline note saying the field was derived rather than read, and field_provenance will record it as "source": "derived". Five rules can do this: the tax head that cannot apply is set to zero from the two state codes; a row's gross is filled from its taxable value and discount, and a row's taxable value from its gross, each the other's exact inverse and never both on one row; the per-line total on a single-line invoice that prints its total only at the foot is filled from the INV-01 item identity; and a document total the model dropped is filled from its row counterpart, again only on a single-line invoice. The last two fire only when the result reconciles with the printed ValDtls.TotInvVal, and a derived value never feeds another derivation across the row/totals boundary. On a multi-line invoice a missing TotItemVal or document total is still reported missing and no payload is produced — see LIMITATIONS.md for why.
Provenance
extraction_meta.field_provenance carries an entry for every field in the payload — 45 for this invoice — saying which stage produced it and, for a scanned page, the OCR confidence of the text it was read from:
{
"SellerDtls.Gstin": { "source": "regex", "ocr_confidence": null },
"SellerDtls.Stcd": { "source": "derived", "ocr_confidence": null },
"ItemList[0].PrdDesc": { "source": "llm", "ocr_confidence": null },
"ItemList[0].IsServc": { "source": "derived", "ocr_confidence": null },
"BuyerDtls.Pos": { "source": "assumed", "ocr_confidence": null }
}On a scanned page the same fields carry real numbers — 0.86 to 0.96 on a clean 300 dpi render — and the lowest confidence across a field's words is the one recorded.
| Meaning |
| Confirmed deterministically, structurally certain |
| Structured by the model, then verified against the document text |
| Follows by rule from values that were read; not printed on the page |
| Neither read nor derived — an assumption the tool names explicitly |
Development
pytest -q -W error1644 tests across ten modules, passing with warnings treated as errors. The LLM stage takes an injected client, so the whole suite runs with no API key and no network.
The suite passes on both 3.11 and 3.13; 3.11 is the floor because that is the lowest version the whole dependency set resolves on, and it was verified by running the suite there rather than assumed.
Testing local changes through an MCP client
The MCP server runs whatever is installed in site-packages, not your working tree. An
MCP client launches the server through the gst-einvoice-mcp entry point, which resolves to
the installed distribution. Editing a file in the repo changes nothing that the server
serves until you reinstall, and there is no error to tell you — the tool call succeeds and
returns the old behaviour.
This is easy to lose an hour to. During the 0.1.2 work the repo carried a new derivation rule while the server was still serving 0.1.1, so a tool call against the new code silently exercised the old path and appeared to show the change had not worked.
Either reinstall after every change:
pip install -e . # editable, so later edits are picked up on server restartor point the MCP client's command at the repo's own virtualenv instead of a user-level
install, so the server and the tests run the same code:
// in your MCP client config
"command": "C:\\path\\to\\repo\\.venv\\Scripts\\gst-einvoice-mcp.exe"Either way, restart the MCP server after changing code — a running server holds the modules it imported at start-up. If a change seems to have no effect, check which copy is being served before looking for the bug in your code.
Module | What it does |
| Structure and mod-36 checksum |
| State code table, including discontinued 25 and legacy 28 |
| INV-01 pydantic models, |
| The four arithmetic and tax-split checks |
| Per-page routing and the detect-and-refuse rules |
| Tesseract with per-word confidence mapped onto character spans |
| Deterministic extraction: GSTINs, parties, number, date, HSN |
| The LLM stage and the grounding check |
| End-to-end assembly |
| The MCP server |
Licence note
This project depends on PyMuPDF, which is AGPL-3.0. That is a deliberate choice, made because PyMuPDF opens image files directly as one-page documents and gave more reliable text-layer detection than the alternatives. If you intend to distribute this tool as part of a closed-source product, check that licence first.
Available Tools
3 toolsparse_invoiceParse an Indian GST tax invoice into an INV-01 payloadA
Read one Indian GST tax invoice (PDF or image) and return the government's INV-01 JSON payload for it, together with the evidence behind every field.
Accepts .pdf, .png, .jpg, .jpeg, .tif, .tiff and .bmp. Pages that carry a text layer are read directly; scanned pages go through OCR, which is slower (budget a few seconds per scanned page).
Returns an object with four keys: invoice the INV-01 payload, or null when none could be produced missing_fields INV-01 paths that are mandatory but could not be read refusals why the document is out of scope, when it is extraction_meta per-page read method, per-field provenance, and warnings
THREE OUTCOMES ARE NORMAL, AND ONLY THE FIRST GIVES YOU A PAYLOAD.
A payload plus warnings. Usable, but read the warnings: they say which fields were read at low OCR confidence, which were assigned by document position rather than by a label, and which were derived rather than printed.
No payload, with missing_fields populated. A mandatory field could not be read from the document. Nothing was invented to fill the gap, which is why there is no payload at all.
No payload, with refusals populated. Export and SEZ invoices and foreign-currency invoices are refused by design; the refusal message says what was detected, which field revealed it, and what to do instead.
The payload is submission-ready in shape, but this tool does NOT file it and does NOT return an IRN. An IRN is issued by the government's Invoice Registration Portal after you submit the payload there.
Requires a Groq API key in the environment; stage 2 uses an LLM to read the line-item table, and every value it returns is checked back against the document text before it is kept.
Inputs: path (required), tolerance. Returns: object
validate_gstinValidate a GSTIN's structure and check digitA
Check one GSTIN (the 15-character Indian GST registration number) against its structural rules and its mod-36 check character, without touching any document.
Returns is_valid, structural_ok, checksum_ok, the state code and its name, the embedded PAN, and a human-readable reason when it fails. checksum_ok is null, not false, when the structure itself failed: the checksum was never evaluated, and reporting two failures where one check ran would be misleading.
State code 25 resolves to a distinct 'discontinued' status rather than 'unknown', because a 25 means either a misread or a genuine pre-2020 record, and the caller needs to tell those apart. State code 28 is legacy-but-valid: pre-2014 Andhra Pradesh registrations remain legitimate.
IMPORTANT: a passing checksum proves the number is well-formed, NOT that the registration exists or is currently active. Only the GST portal can tell you that.
Inputs: gstin (required). Returns: object
validate_payloadRun the arithmetic and tax-split checks over an INV-01 payloadA
Take an INV-01 payload you already have and run the same consistency checks the parser runs, without re-reading any document. Useful for a payload you assembled yourself, or one you edited after parsing.
Four checks run: each item's total against its own components; the invoice total against the value block; each value-block total against the sum of the item fields; and the CGST/SGST-versus-IGST split against the two parties' state codes.
Comparisons use a rupee tolerance (0.05 by default), never exact equality, because real invoices round to the nearest rupee and exact comparison would flag almost every genuine document.
Returns valid (true when nothing was flagged), the warning list with the exact field path for each, and schema_error when the payload does not fit INV-01 at all. The tax-split check reports itself as skipped, as an informational note rather than a warning, under reverse charge and when the place of supply differs from the buyer's registered state, because it cannot evaluate those cases.
Inputs: invoice (required), tolerance. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct stage of the e-invoicing workflow: validating a GSTIN, parsing an invoice document into an INV-01 payload, and validating a payload's internal consistency. There is no functional overlap between them.
All three tool names follow a consistent verb_noun pattern: validate_gstin, parse_invoice, validate_payload. The verbs and nouns clearly describe the action and resource, with no mixed conventions.
Three tools is well-scoped for a focused GST e-invoice MCP server covering the core pipeline: GSTIN validation, invoice parsing, and payload validation. Each tool addresses a distinct need without bloat or obvious missing essentials for the stated purpose.
The tool set covers the main pre-filing workflow: validating the seller's GSTIN, extracting an INV-01 payload from an invoice document, and validating that payload before submission. It does not include submission or IRN generation by design, but that is explicitly delegated to the government portal, so the gap is intentional.
Maintenance
Related MCP Connectors
PDF tools + invoice extraction, bank statement parsing, GST reconciliation & GSTIN validation.
Create, validate, convert & extract compliant e-invoices (UBL, Factur-X, ZUGFeRD, XRechnung)
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.
Validate, generate & convert EU e-invoices (UBL, CII, XRechnung, Factur-X) — EN 16931 pre-validated.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExtracts structured JSON from receipts and invoices with Australian GST/ABN validation, per-line tax codes, confidence scores, and rationale.2-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to build and structurally validate Indian GST e-invoice JSON payloads (INV/CRN/DBN) and render IRP-returned signed QR strings as PNG images.1Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables accounts payable teams to extract invoice data from PDFs and images, detect duplicates, normalize vendor names, calculate payment terms, and validate invoice completeness. Supports local extraction for text PDFs and optional vision providers for scanned documents.-

rechnungsapi-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants and agents to create, validate, read and convert German and EU e-invoices in ZUGFeRD, XRechnung and Factur-X formats, including extracting structured data from scanned or PDF invoices and embedding XML into PDF/A-3 files. It can run as a hosted remote server or locally, with each request authenticated by the caller's own API token.1024 npmMIT