Content
# 🧾 GSTR-1 MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that enables AI assistants to file Indian GST GSTR-1 returns via the GST portal sandbox APIs.
Works with **Claude Desktop**, **Kiro**, **ChatGPT** (with MCP plugin), **Cursor**, **Windsurf**, and any MCP-compatible client.
## What It Does
This server wraps the Indian GST portal's GSTR-1 APIs into 8 tools that AI assistants can call:
| # | Tool | Description |
|---|------|-------------|
| 1 | `generate_taxpayer_session` | Full auth flow — generates app key, requests OTP, gets auth token |
| 2 | `save_gstr1_data` | Upload invoice data (b2b, b2cl, b2cs, hsn sections) |
| 3 | `check_return_status` | Poll async processing status until COMPLETED |
| 4 | `proceed_to_file` | Initiate filing after data validation |
| 5 | `get_gstr1_summary` | Get section summaries + checksum for filing |
| 6 | `generate_evc_otp` | Request Electronic Verification Code OTP |
| 7 | `file_gstr1` | Final submission with EVC OTP → returns ARN |
| 8 | `convert_excel_to_payload` | Convert GSTR-1 Excel workbook to API JSON |
## Prerequisites
1. **uv** — Python package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **GST Sandbox Public Key Certificate** — bundled in `certs/` directory (no download needed for sandbox)
3. **GSP Credentials** — `client-id` and `client-secret` from your GSP onboarding
## Quick Start
### 1. Clone the repo
```bash
git clone https://github.com/vishnu27597/gstr1-mcp-server.git
cd gstr1-mcp-server
```
### 2. Set up environment
```bash
cp .env.example .env
# Edit .env with your credentials and cert path
```
### 3. Configure your MCP client
Add the server to your MCP client's configuration file.
---
## MCP Client Setup
### Kiro
Edit `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` in your workspace):
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/absolute/path/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
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/gstr1-mcp-server",
"run", "gstr1-mcp-server"
],
"env": {
"GST_CLIENT_ID": "3jXXbtwkLpt+dd5bAxQKBxTAHGv4nnLl+nwcapkmvK8=",
"GST_CLIENT_SECRET": "aox4PGWgcFv3MCRUPxf30TQ8t2v6c48mhptufG1QEAk5uu048yfUlPp4tIG5gY2gr4eYTRe6+5p7ehbqXZdvXg==",
"GST_CERT_PATH": "/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
Edit `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"gstr1": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/gstr1-mcp-server",
"run", "gstr1-mcp-server"
],
"env": {
"GST_CLIENT_ID": "3jXXbtwkLpt+dd5bAxQKBxTAHGv4nnLl+nwcapkmvK8=",
"GST_CLIENT_SECRET": "aox4PGWgcFv3MCRUPxf30TQ8t2v6c48mhptufG1QEAk5uu048yfUlPp4tIG5gY2gr4eYTRe6+5p7ehbqXZdvXg==",
"GST_CERT_PATH": "/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"
}
}
}
}
```
---
## Environment Variables
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `GST_CLIENT_ID` | Yes | GSP client ID (Base64 encoded) | `3jXXbtwkLpt+...` |
| `GST_CLIENT_SECRET` | Yes | GSP client secret (Base64 encoded) | `aox4PGWgcFv3...` |
| `GST_CERT_PATH` | No | Override path to `.cer` file (sandbox cert bundled) | `/path/to/cert.cer` |
| `GST_USERNAME` | Yes | Taxpayer username for sandbox | `TN_NT2.21475` |
| `GST_STATE_CD` | Yes | 2-digit state code | `33` |
| `GST_BASE_URL` | No | API base URL (defaults to sandbox) | `https://staging-passthrough.gsp.amazon.dev` |
---
## Filing Workflow
Here's how an AI assistant uses the tools to file a GSTR-1 return:
```
Step 1: generate_taxpayer_session
↓ (returns access_token)
Step 2: save_gstr1_data (with invoice JSON payload)
↓ (returns reference_id)
Step 3: check_return_status (poll until COMPLETED)
↓
Step 4: proceed_to_file
↓ (returns reference_id)
→ check_return_status (poll until COMPLETED)
↓
Step 5: get_gstr1_summary
↓ (returns sec_sum + chksum)
Step 6: generate_evc_otp
↓ (OTP sent to taxpayer)
Step 7: file_gstr1 (with OTP + sec_sum + chksum)
↓ (returns ARN — filing acknowledgement)
```
### Example: Save a B2B Invoice
Ask your AI assistant:
> "File my GSTR-1 for March 2026. My GSTIN is 33CMNPP5324B9Z0, username TN_NT2.21475. I have one B2B invoice: invoice number TEST-INV-001, dated 15-03-2026, value ₹10,000, to buyer GSTIN 33GSPTN0161G1ZH, 18% GST intra-state."
The assistant will:
1. Call `generate_taxpayer_session` to authenticate
2. Call `save_gstr1_data` with the invoice payload
3. Call `check_return_status` to confirm processing
4. Continue through the filing workflow
### Example: Convert Excel and File
> "Convert my GSTR-1 Excel at /path/to/GSTR1_output_032026.xlsx and file it for March 2026."
The assistant will:
1. Call `convert_excel_to_payload` to read the Excel
2. Call `generate_taxpayer_session` to authenticate
3. Call `save_gstr1_data` with the converted payload
4. Complete the filing workflow
---
## Sandbox Details
| Property | Value |
|----------|-------|
| Base URL | `https://staging-passthrough.gsp.amazon.dev` |
| Auth API | `/taxpayerapi/v1.0/authenticate` |
| Returns API | `/taxpayerapi/v4.0/returns/gstr1` |
| Sandbox OTP | `575757` (no real OTP needed) |
| Test GSTIN | `33CMNPP5324B9Z0` |
| Test Username | `TN_NT2.21475` |
| State Code | `33` (Tamil Nadu) |
| Counter-party GSTIN | `33GSPTN0161G1ZH` |
| Token Expiry | 360 minutes |
---
## API Payload Rules
- **Intra-state** (seller state = POS): use `camt` (CGST) + `samt` (SGST). Never `iamt`.
- **Inter-state** (seller state ≠ POS): use `iamt` (IGST). Never `camt`/`samt`.
- **Invoice date**: `DD-MM-YYYY` in API payload
- **Return period**: `MMYYYY` format (e.g. `032026`), must not be future month
- **Batching**: Multiple `save_gstr1_data` calls allowed. System stores the union. Same invoice number replaces previous.
---
## Development
```bash
# Install dependencies
uv sync
# Run the server locally
uv run gstr1-mcp-server
# Run tests
uv run pytest
```
---
## Project Structure
```
gstr1-mcp-server/
├── pyproject.toml # Package config + dependencies
├── README.md
├── LICENSE # MIT
├── .env.example # Credential template
├── .gitignore
├── certs/
│ └── GSTN_G2B_SANDBOX_UAT_public.cert.cer # Bundled sandbox cert
├── schemas/
│ ├── gstr1_schema.json # Official GSTR-1 upload schema v2.4
│ └── sample_payload.json # Sample GSTR-1 payload from GST portal
└── src/
└── gstr1_mcp_server/
├── __init__.py
├── server.py # MCP server + 8 tool definitions
├── crypto.py # AES/RSA encryption for GST APIs
├── gst_api.py # HTTP client + session management
└── excel_converter.py # GSTR-1 Excel → API JSON converter
```
---
## License
MIT
---
## References
- [GST Developer Portal — API Documentation](https://developer.gst.gov.in/apiportal/taxpayer/returns)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [uv — Python Package Manager](https://docs.astral.sh/uv/)
