内容
# 🧾 GSTR-1 MCP 服务器
一款 [MCP (模型上下文协议)](https://modelcontextprotocol.io/) 服务器，使 AI 助手能够通过 GST 门户沙盒 API 提交印度 GST GSTR-1 申报表。
与 **Claude Desktop**、**Kiro**、**ChatGPT** (带有 MCP 插件)、**Cursor**、**Windsurf** 以及任何兼容 MCP 的客户端配合使用。
## 功能
该服务器将印度 GST 门户的 GSTR-1 API 封装为 8 种工具，AI 助手可以调用这些工具：
| # | 工具 | 描述 |
|---|------|-------------|
| 1 | `generate_taxpayer_session` | 完整的身份验证流程 — 生成应用密钥，请求 OTP，获取身份验证令牌 |
| 2 | `save_gstr1_data` | 上传发票数据（b2b, b2cl, b2cs, hsn 部分） |
| 3 | `check_return_status` | 轮询异步处理状态，直到 COMPLETED |
| 4 | `proceed_to_file` | 在数据验证后发起申报 |
| 5 | `get_gstr1_summary` | 获取章节摘要 + 用于申报的校验和 |
| 6 | `generate_evc_otp` | 请求电子验证代码 OTP |
| 7 | `file_gstr1` | 最终提交，附带 EVC OTP → 返回 ARN |
| 8 | `convert_excel_to_payload` | 将 GSTR-1 Excel 工作簿转换为 API JSON |
## 前置条件
1. **uv** — Python 包管理器 ([安装指南](https://docs.astral.sh/uv/getting-started/installation/))
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **GST 沙盒公共密钥证书** — 包含在 `certs/` 目录中（沙盒环境无需下载）
3. **GSP 凭证** — 来自 GSP 注册的 `client-id` 和 `client-secret`
## 快速入门
### 1. 克隆仓库
```bash
git clone https://github.com/vishnu27597/gstr1-mcp-server.git
cd gstr1-mcp-server
```
### 2. 设置环境
```bash
cp .env.example .env
# 使用您的凭证和证书路径编辑 .env
```
### 3. 配置 MCP 客户端
将服务器添加到 MCP 客户端的配置文件中。
---
## MCP 客户端设置
### Kiro
编辑 `~/.kiro/settings/mcp.json`（或工作区中的 `.kiro/settings/mcp.json`）：
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/绝对路径/to/gstr1-mcp-server",
"run", "gstr1-mcp-server"
],
"env": {
"GST_CLIENT_ID": "3jXXbtwkLpt+dd5bAxQKBxTAHGv4nnLl+nwcapkmvK8=",
"GST_CLIENT_SECRET": "aox4PGWgcFv3MCRUPxf30TQ8t2v6c48mhptufG1QEAk5uu048yfUlPp4tIG5gY2gr4eYTRe6+5p7ehbqXZdvXg==",
"GST_USERNAME": "TN_NT2.21475",
"GST_STATE_CD": "33"
}
}
}
}
```
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/绝对路径/to/gstr1-mcp-server",
"run", "gstr1-mcp-server"
],
"env": {
"GST_CLIENT_ID": "3jXXbtwkLpt+dd5bAxQKBxTAHGv4nnLl+nwcapkmvK8=",
"GST_CLIENT_SECRET": "aox4PGWgcFv3MCRUPxf30TQ8t2v6c48mhptufG1QEAk5uu048yfUlPp4tIG5gY2gr4eYTRe6+5p7ehbqXZdvXg==",
"GST_CERT_PATH": "/路径/to/GSTN_G2B_SANDBOX_UAT_public.cert.cer",
"GST_USERNAME": "TN_NT2.21475",
"GST_STATE_CD": "33",
"GST_BASE_URL": "https://staging-passthrough.gsp.amazon.dev"
}
}
}
}
```
### Cursor
编辑项目根目录下的 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/绝对路径/to/gstr1-mcp-server",
"run", "gstr1-mcp-server"
],
"env": {
"GST_CLIENT_ID": "3jXXbtwkLpt+dd5bAxQKBxTAHGv4nnLl+nwcapkmvK8=",
"GST_CLIENT_SECRET": "aox4PGWgcFv3MCRUPxf30TQ8t2v6c48mhptufG1QEAk5uu048yfUlPp4tIG5gY2gr4eYTRe6+5p7ehbqXZdvXg==",
"GST_CERT_PATH": "/路径/to/GSTN_G2B_SANDBOX_UAT_public.cert.cer",
"GST_USERNAME": "TN_NT2.21475",
"GST_STATE_CD": "33",
"GST_BASE_URL": "https://staging-passthrough.gsp.amazon.dev"
}
}
}
}
```
---
## 环境变量
| 变量 | 是否必需 | 描述 | 示例 |
|----------|----------|-------------|---------|
| `GST_CLIENT_ID` | 是 | GSP 客户端 ID（Base64 编码） | `3jXXbtwkLpt+...` |
| `GST_CLIENT_SECRET` | 是 | GSP 客户端密钥（Base64 编码） | `aox4PGWgcFv3...` |
| `GST_CERT_PATH` | 否 | `.cer` 文件路径的重写（沙盒证书已捆绑） | `/路径/to/cert.cer` |
| `GST_USERNAME` | 是 | 沙盒纳税人用户名 | `TN_NT2.21475` |
| `GST_STATE_CD` | 是 | 2 位州代码 | `33` |
| `GST_BASE_URL` | 否 | API 基本 URL（默认为沙盒） | `https://staging-passthrough.gsp.amazon.dev` |
---
## 申报工作流程
以下是 AI 助手如何使用工具提交 GSTR-1 申报表的流程：
```
步骤 1：generate_taxpayer_session
↓ （返回 access_token）
步骤 2：save_gstr1_data（附带发票 JSON 负载）
↓ （返回 reference_id）
步骤 3：check_return_status（轮询直到 COMPLETED）
↓
步骤 4：proceed_to_file
↓ （返回 reference_id）
→ check_return_status（轮询直到 COMPLETED）
↓
步骤 5：get_gstr1_summary
↓ （返回 sec_sum + chksum）
步骤 6：generate_evc_otp
↓ （向纳税人发送 OTP）
步骤 7：file_gstr1（附带 OTP + sec_sum + chksum）
↓ （返回 ARN — 申报确认）
```
### 示例：保存 B2B 发票
询问您的 AI 助手：
> "请为 2026 年 3 月提交我的 GSTR-1 申报表。我的 GSTIN 是 33CMNPP5324B9Z0，用户名是 TN_NT2.21475。我有一张 B2B 发票：发票号码 TEST-INV-001，日期 2026-03-15，价值 ₹10,000，买方 GSTIN 33GSPTN0161G1ZH，18% GST 省内。"
助手将：
1. 调用 `generate_taxpayer_session` 进行身份验证
2. 调用 `save_gstr1_data` 并附上发票负载
3. 调用 `check_return_status` 以确认处理
4. 继续完成申报工作流程
### 示例：转换 Excel 并申报
> "将我的 GSTR-1 Excel 文件 `/路径/to/GSTR1_output_032026.xlsx` 转换为 2026 年 3 月的申报表。"
助手将：
1. 调用 `convert_excel_to_payload` 读取 Excel 文件
2. 调用 `generate_taxpayer_session` 进行身份验证
3. 调用 `save_gstr1_data` 并附上转换后的负载
4. 完成申报工作流程
---
## 沙盒详情
| 属性 | 值 |
|----------|-------|
| 基本 URL | `https://staging-passthrough.gsp.amazon.dev` |
| 身份验证 API | `/taxpayerapi/v1.0/authenticate` |
| 申报 API | `/taxpayerapi/v4.0/returns/gstr1` |
| 沙盒 OTP | `575757`（无需真实 OTP） |
| 测试 GSTIN | `33CMNPP5324B9Z0` |
| 测试用户名 | `TN_NT2.21475` |
| 州代码 | `33`（泰米尔纳德邦） |
| 对方 GSTIN | `33GSPTN0161G1ZH` |
| 令牌过期时间 | 360 分钟 |
---
## API 负载规则
- **省内**（卖方州 = 销售地点）：使用 `camt`（CGST）+ `samt`（SGST）。绝不能使用 `iamt`。
- **省际**（卖方州 ≠ 销售地点）：使用 `iamt`（IGST）。绝不能使用 `camt`/`samt`。
- **发票日期**：API 负载中的 `DD-MM-YYYY` 格式
- **申报期**：`MMYYYY` 格式（例如 `032026`），不能是未来月份
- **批处理**：允许多个 `save_gstr1_data` 调用。系统存储联合数据。相同的发票号码会替换以前的。
---
## 开发
```bash
# 安装依赖
uv sync
# 在本地运行服务器
uv run gstr1-mcp-server
# 运行测试
uv run pytest
```
---
## 项目结构
```
gstr1-mcp-server/
├── pyproject.toml # 包配置 + 依赖
├── README.md
├── LICENSE # MIT
├── .env.example # 凭证模板
├── .gitignore
├── certs/
│ └── GSTN_G2B_SANDBOX_UAT_public.cert.cer # 捆绑的沙盒证书
├── schemas/
│ ├── gstr1_schema.json # 官方 GSTR-1 上传模式 v2.4
│ └── sample_payload.json # 来自 GST 门户的示例 GSTR-1 负载
└── src/
└── gstr1_mcp_server/
├── __init__.py
├── server.py # MCP 服务器 + 8 种工具定义
├── crypto.py # GST API 的 AES/RSA 加密
├── gst_api.py # HTTP 客户端 + 会话管理
└── excel_converter.py # GSTR-1 Excel → API JSON 转换器
```
---
## 许可证
MIT
---
## 参考
- [GST 开发者门户 — API 文档](https://developer.gst.gov.in/apiportal/taxpayer/returns)
- [模型上下文协议规范](https://modelcontextprotocol.io/)
- [uv — Python 包管理器](https://docs.astral.sh/uv/)
