mcp-einvoicing-in

mcp-einvoicing-in 🇮🇳

English | हिन्दी

一个 Python MCP 服务，为印度 GST 电子发票提供工具，遵循 GSTN 的 FORM GST INV-01 schema v1.1（《CGST Act 2017》第 31 条 +《CGST Rule 48(4)》，第 68/2019-Central Tax 号通知）。它 支持 AI Agent（Claude、IDE）构建并进行结构验证 GST 电子发票 JSON 负载 （INV、CRN、DBN 文档类型），并将 IRP 返回的已签名 QR 字符串渲染为可显示的图像。

阶段 A 范围。 此软件包仅涵盖离线负载构建、结构验证和 GSTIN 税务标识符验证。它不会提交到 Invoice Registration Portal (IRP)——实时提交（身份验证/令牌、生成 IRN、取消 IRN）属于后续阶段，当前项目尚无法获取 NIC 电子发票 API 规范，因此相关工作受阻（见下文“规范可用性”）。有关当前已实现功能的具体信息，请参阅可用工具。

---

简介

此软件包基于 mcp-einvoicing-core 构建，这是电子发票 MCP 服务的共享基础库。它提供 InvoiceDocument 模型基类 和 TaxIdentifier.validate_in_gstin GSTIN 验证器。

mcp-einvoicing-core 会作为依赖自动安装，无需额外操作。

GST 电子发票采用清算模式：只有当 IRP（Invoice Registration Portal，由 NIC 运营）验证供应商的 JSON 负载，并返回发票参考编号 (IRN)、确认编号/日期及已签名 QR 码后，发票才具有法律效力（《CGST Rule 48(4)/(5)》）。此软件包用于构建并进行结构验证的，是供应商将要提交的请求负载；它本身不会提交到 IRP（见上文“阶段 A 范围”）。

安装

通过 PyPI（推荐）

pip install mcp-einvoicing-in

也可以使用 uvx，无需预先安装：

uvx mcp-einvoicing-in

从源代码安装

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

配置

此软件包在当前（阶段 A）范围内不需要任何环境变量，因为它不会发出网络请求。实现实时 IRP 提交后，将需要 IRP/GSP 凭据；届时会更新本节。

Claude Desktop 集成

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

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

Cursor 集成

将相同的 mcpServers 配置块添加到以下任一文件：

• 全局配置：~/.cursor/mcp.json
• 项目专用配置：项目根目录下的 .cursor/mcp.json

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

保存后重新加载 Cursor（或从命令面板运行“Reload Window”）。

Kiro 集成

将以下内容添加到任一文件：

• 全局配置：~/.kiro/settings/mcp.json
• 工作区配置：.kiro/settings/mcp.json

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

Kiro 会在保存时自动重新加载 MCP 配置。如果此软件包的未来版本需要凭据，建议使用 "VAR_NAME": "${VAR_NAME}" shell 插值语法，而不是在此文件中存储明文密钥。

可用工具

范围

• in__get_supported_scope — 返回此软件包当前支持的文档类型、供应类型和明确不在范围内的事项。

构建和验证

• in__build_invoice — 根据 INInvoice 验证结构化输入，并构建 GST 电子发票 JSON 负载（INV/CRN/DBN）。绝不会生成 IRN——该字段由 IRP 生成，不由供应商填写。
• in__validate_invoice — 离线结构和业务规则验证：必填字段、枚举成员资格、CGST+SGST 与 IGST 的配对情况（项目级和文档总额级），以及 GSTIN/州代码的一致性。不会执行 XSD/Schematron 验证——FORM GST INV-01 是 JSON，而不是 XML。

QR

• in__render_irp_qr_png — 将 IRP 返回的签名 QR 字符串渲染为可显示的 PNG。不解码或解释 QR 的内容——描述该内容的 NIC 电子发票 API 规范目前尚未提供给本项目（见下文“规范可用性”）。

规范可用性

从印度境外获取当前且准确的 NIC/GSTN 技术规范并不可靠：GSTN 实施严格的地理防火墙，经常拦截或限制非印度 IP 地址。本软件包完全基于维护者直接提供的规范文档构建（FORM GST INV-01 schema v1.1；CGST Notifications 68/2019-CT 和 72/2020-CT；以及确认当前 AATO 强制要求门槛的 Notification No. 10/2023-CT）——没有自动化 Agent 从互联网上获取任何文档。因此：

• 本项目尚未提供： specs/README.md“待补充规范”表格中的完整列表。
• 如无 NIC 电子发票 API 规范，就无法负责任地构建实时 IRP 提交工具——见“Phase A 范围”。

如果您身在印度，并且可以提供其中列出的任何文档，请使用 规范更新问题模板提交 issue。模板会收集文档名称、官方来源 URL、版本和获取日期；随后通过 pull request 将文件添加到 specs/，并附上来源表条目以及来源证明/再分发声明。完整的两步流程请见 CONTRIBUTING.md。

架构

INInvoice 是 InvoiceDocument（mcp_einvoicing_core.models）的子类——FORM GST INV-01 与 EN 16931/UBL/CII 没有渊源关系（它是一种扁平的 JSON 清关模型 schema），因此本软件包采用 InvoiceDocument 路径，与 mcp-cfdi-mx（CFDI）和 mcp-nfe-br（NF-e）使用的路径相同。INInvoiceLine 是 InvoiceLineItem 的子类，用于添加 schema 中的 GST/HSN/cess 字段，这些字段在基础行项目模型中没有对应项。GSTIN 字段通过 TaxIdentifier.validate_in_gstin 验证，该方法由 INInvoice 自身的模型验证器调用——本软件包不会在本地重新实现标识符验证逻辑。由于线上格式是 JSON，而不是 XML，因此没有 Schematron/XSD 验证层（validators/structural.py 改为实现纯 Python 业务规则检查）。

供应商中立性

此服务实现标准本身：在本地构建并验证文档。它不是商业开票平台的客户端，您的凭证也绝不会离开您自己的基础设施。

连接 IRP 需要 GSP（GST Suvidha Provider）；本软件包会在本地构建并进行结构验证，但实时 IRP 提交功能尚未实现，等待 NIC API 规范提供后再行开发（见上文“规范可用性”）。

贡献

有关开发环境设置、PR 检查清单和提交规范，请见 CONTRIBUTING.md。

其他电子发票 MCP 服务

国家/地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿拉伯联合酋长国	mcp-einvoicing-ae

许可证

本项目采用 Apache 2.0 许可证，详情请参阅 LICENSE。 完整版本历史请参阅 CHANGELOG.md。