411sst/gst-einvoice-mcp

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.
------
Install
Requires **Python 3.11 or newer** and **Tesseract OCR** as a system dependency.
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 |
| ------------------- | ----------- | ---------------------------------------------- |
| GROQ_API_KEY | yes | Stage 2 reads the line-item table through Groq |
| GST_MCP_MODEL | recommended | Pin the model your key can reach |
| GST_MCP_TRANSPORT | no | stdio (default), sse, or streamable-http |
The default model is openai/gpt-oss-120b, which is what this release was validated against. It works without configuration.
> **Still set GST_MCP_MODEL in 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:
Running from a clone rather than an install? Point command at the interpreter inside your virtual environment and invoke the module directly:
On Windows that interpreter path ends \.venv\Scripts\python.exe.
Tools
| Tool | Takes | Gives back |
| ------------------ | ------------------------------- | ------------------------------------------------------------ |
| parse_invoice | a file path, optional tolerance | the INV-01 payload, missing fields, refusals, and extraction_meta |
| validate_gstin | a GSTIN | structure, checksum, state code, PAN, and the reason on failure |
| validate_payload | 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:
1. **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.