Sandbox GSTR-1 MCP Server
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., "@Sandbox GSTR-1 MCP Server Save GSTR-1 B2B data for period 072024 using the uploaded Excel file."
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.
Sandbox GSTR-1 MCP Server
A powerful Model Context Protocol (MCP) server for automating GSTR-1 (Goods and Services Tax Return - 1) filing through the Sandbox.co APIs. Seamlessly integrate with Claude Desktop or Claude API to automate your GST return filing process.
๐ Quick Start
For Claude Desktop Users
Clone the repository:
git clone https://github.com/yourusername/sandbox-gstr1-mcp.git cd sandbox-gstr1-mcpInstall dependencies:
pip install -r requirements.txtAdd to Claude Desktop:
Open your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add this configuration:
{ "mcpServers": { "sandbox-gstr1": { "command": "python", "args": ["/path/to/sandbox-gstr1-mcp/server.py"], "env": { "SANDBOX_API_KEY": "key_test_ed6b10d21cf546d7b4b600021f91c341", "SANDBOX_API_SECRET": "secret_test_798d3274325741fab93dd24bbb786a3a" } } } }
Restart Claude Desktop and start using the GSTR-1 filing tools!
For Developers
# Clone and setup
git clone https://github.com/yourusername/sandbox-gstr1-mcp.git
cd sandbox-gstr1-mcp
# Install dependencies
pip install -r requirements.txt
# Run the server
export SANDBOX_API_KEY="key_test_ed6b10d21cf546d7b4b600021f91c341"
python server.pyRelated MCP server: GoHighLevel MCP Server
๐ Features
Complete GSTR-1 Filing Workflow
โ Taxpayer Authentication: Generate and manage 6-hour sessions
โ Data Submission: Save B2B, B2CL, B2CS, HSN, and document data
โ Status Monitoring: Real-time filing status tracking
โ Filing Initialization: Prepare returns for submission
โ Summary Retrieval: Get section-wise summaries and checksums
โ OTP Generation: Electronic Verification Code generation
โ Return Filing: Submit final GSTR-1 with OTP verification
โ Excel Conversion: Transform Excel output to API format
Supported GSTR-1 Sections
Section | Type | Description |
B2B | Business-to-Business | Regular invoices to registered businesses |
B2CL | B2C Large | Large value B2C invoices (>โน1,00,000 from Aug 2024) |
B2CS | B2C Small | Aggregated B2C transactions |
HSN | Summary | Harmonized System of Nomenclature aggregation |
Credit Notes | Amendments | For refunds and adjustments |
Exports | International | Export transactions |
Amendments | Revisions | Amendments to previously filed returns |
๐ ๏ธ Available Tools
The MCP server exposes 8 powerful tools for GSTR-1 filing:
1. Generate Taxpayer Session
generate_taxpayer_session(gstin, username)Creates a 6-hour valid taxpayer session token.
2. Save GSTR-1 Data
save_gstr1_data(access_token, gstin, ret_period, gstr1_data)Uploads GSTR-1 data for validation.
3. Check Return Status
check_return_status(access_token, gstin, ret_period, reference_id)Monitors filing operation status.
4. Proceed to File
proceed_to_file(access_token, gstin, ret_period, is_nil)Initializes the filing process.
5. Get GSTR-1 Summary
get_gstr1_summary(access_token, gstin, ret_period, summary_type)Retrieves section summaries and checksums.
6. Generate EVC OTP
generate_evc_otp(access_token, pan)Generates Electronic Verification Code OTP.
7. File GSTR-1
file_gstr1(access_token, gstin, ret_period, pan, otp, sec_sum, chksum)Submits the final GSTR-1 return.
8. Convert Excel to Sandbox Payload
convert_excel_to_sandbox_payload(excel_path)Transforms Excel output to API format.
๐ Documentation
README.md - Comprehensive API documentation and workflow details
CONFIGURATION.md - Setup, configuration, and deployment guide
EXAMPLES.md - Practical code examples for various scenarios
CLAUDE_INTEGRATION.md - Claude Desktop and API integration guide
๐ง Configuration
Environment Variables
# Required
export SANDBOX_API_KEY="key_test_ed6b10d21cf546d7b4b600021f91c341"
export SANDBOX_API_SECRET="secret_test_798d3274325741fab93dd24bbb786a3a"
# Optional
export SANDBOX_API_URL="https://api.sandbox.co.in"
export SANDBOX_API_VERSION="1.0.0"
export LOG_LEVEL="INFO"Test Credentials
The server comes pre-configured with test credentials that don't consume quota:
API Key:
key_test_ed6b10d21cf546d7b4b600021f91c341API Secret:
secret_test_798d3274325741fab93dd24bbb786a3aEnvironment: Test (safe for development)
๐ GSTR-1 Filing Workflow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1. Generate Taxpayer Session (6-hour validity) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 2. Save GSTR-1 Data (B2B, B2CL, B2CS, HSN, etc.) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 3. Check Return Status (Poll until complete) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 4. Proceed to File (Initialize filing) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 5. Get GSTR-1 Summary (Get checksums) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 6. Generate EVC OTP (For verification) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 7. File GSTR-1 (Submit with OTP) โ
โโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โ
Filing Complete๐งช Testing
Run the comprehensive test suite:
python test_server.pyExpected output:
============================================================
Test Summary
============================================================
โ PASSED: Imports
โ PASSED: API Endpoints
โ PASSED: Payload Structure
โ PASSED: Credentials
โ PASSED: Workflow
Total: 5/5 tests passed
============================================================๐ฌ Using with Claude
Claude Desktop
Once configured, use natural language:
"File a GSTR-1 return for GSTIN 29AAACQ3770E000 for March 2026"
"Generate a taxpayer session and save GSTR-1 data with B2B invoices"
"Check the status of my GSTR-1 filing with reference ID xyz123"
"Convert my GSTR-1 Excel file to the Sandbox API format"Claude API
import anthropic
client = anthropic.Anthropic(api_key="your-api-key")
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
tools=[...], # MCP tools
messages=[
{
"role": "user",
"content": "File a GSTR-1 return for GSTIN 29AAACQ3770E000"
}
]
)๐ฆ Installation Methods
Method 1: Direct Installation (Recommended)
git clone https://github.com/yourusername/sandbox-gstr1-mcp.git
cd sandbox-gstr1-mcp
pip install -r requirements.txtMethod 2: Using Virtual Environment
git clone https://github.com/yourusername/sandbox-gstr1-mcp.git
cd sandbox-gstr1-mcp
python3.11 -m venv venv
source venv/bin/activate # macOS/Linux
# or
venv\Scripts\activate # Windows
pip install -r requirements.txtMethod 3: Docker
docker build -t sandbox-gstr1-mcp:1.0.0 .
docker run -e SANDBOX_API_KEY="your-key" sandbox-gstr1-mcp:1.0.0๐ Security
โ Test credentials provided for safe development
โ Environment variables for sensitive data
โ No credentials in code or version control
โ HTTPS for all API calls
โ Comprehensive error handling and logging
๐ Troubleshooting
MCP Server Not Appearing in Claude Desktop
Verify configuration file path is correct
Check Python path is accessible
Ensure all dependencies are installed
Restart Claude Desktop completely
Check Claude logs for errors
API Connection Errors
Verify API key is correct
Check internet connectivity
Confirm API URL is correct
Review server logs for details
Session Expired
Generate a new taxpayer session (valid for 6 hours).
For more troubleshooting, see CLAUDE_INTEGRATION.md.
๐ Examples
File a Nil Return
from server import generate_taxpayer_session, save_gstr1_data
session = generate_taxpayer_session(
gstin="29AAACQ3770E000",
username="taxpayer_username"
)
save_gstr1_data(
access_token=session["access_token"],
gstin="29AAACQ3770E000",
ret_period="032026",
gstr1_data={
"fp": "032026",
"gstin": "29AAACQ3770E000",
"gt": 0,
"cur_gt": 0,
"b2b": [],
"b2cl": [],
"b2cs": [],
"hsn": {"data": []},
"docs": {"doc_det": []}
}
)File B2B Invoices
See EXAMPLES.md for complete examples including:
B2B invoices
B2CL large value invoices
B2CS small value transactions
HSN summaries
Credit notes
Error handling
Complete end-to-end workflow
๐ค Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Write tests
Submit a pull request
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Resources
Sandbox.co - GST API Platform
Sandbox Developer Hub - API Documentation
Claude Desktop - AI Assistant
MCP Protocol - Protocol Documentation
GST Portal - Official GST Portal
๐ Support
For issues or questions:
Check the troubleshooting guide
Review the documentation
Check examples
Open an issue on GitHub
๐ฏ Roadmap
Support for GSTR-3B filing
Support for GSTR-9 filing
Batch filing for multiple returns
Webhook support for filing notifications
Dashboard for filing history
Multi-language support
Advanced error recovery
๐ Status
Component | Status |
Core Server | โ Production Ready |
API Integration | โ Complete |
Claude Desktop | โ Tested |
Claude API | โ Supported |
Documentation | โ Comprehensive |
Tests | โ Passing |
๐ Acknowledgments
Built on top of Sandbox.co APIs
Integrates with Claude via MCP Protocol
Inspired by the unified GSTR-1 skill
๐ Changelog
v1.0.0 (April 1, 2026)
Initial release
Complete GSTR-1 filing workflow
All 7 core tools implemented
Excel to JSON conversion
Comprehensive documentation
Full test suite
Claude Desktop integration
Claude API support
Made with โค๏ธ for GST compliance automation
Version: 1.0.0
Last Updated: April 1, 2026
Python: 3.11+
License: MIT
Available Tools
8 toolscheck_return_statusA
Poll the status of a save or proceed operation (Step 3).
Call this repeatedly (every 5 seconds) until status == "COMPLETED".
Args: access_token: Taxpayer session token gstin: 15-digit GST Identification Number ret_period: Return period in MMYYYY format reference_id: The reference_id returned by save_gstr1_data() or proceed_to_file()
Returns: Dict with status field ("PENDING", "PROCESSING", "COMPLETED", "ERROR").
Inputs: gstin (required), ret_period (required), access_token (required), reference_id (required). Returns: result
convert_excel_to_sandbox_payloadA
Convert a GSTR-1 Excel file (output of the unified-gstr1 skill) into the JSON payload format required by the Sandbox.co save_gstr1_data() API.
Reads the b2b, b2cl, b2cs, and hsn sheets from the Excel file and maps each row to the corresponding Sandbox.co API structure.
Args: excel_path: Absolute path to the GSTR-1 Excel file
Returns: Dict with the formatted payload ready to pass to save_gstr1_data(), or an error dict.
Inputs: excel_path (required). Returns: result
file_gstr1A
Submit the final GSTR-1 return with EVC OTP verification (Step 7 โ final step).
Args: access_token: Taxpayer session token gstin: 15-digit GST Identification Number ret_period: Return period in MMYYYY format pan: Permanent Account Number otp: EVC OTP received after calling generate_evc_otp() sec_sum: Section summaries array from get_gstr1_summary() chksum: Checksum string from get_gstr1_summary()
Returns: Dict with filing acknowledgement number (ARN) and status, or an error dict.
Inputs: otp (required), pan (required), gstin (required), chksum (required), +3 more. Returns: result
generate_evc_otpA
Generate an Electronic Verification Code (EVC) OTP for filing (Step 6).
The OTP is sent to the mobile number and email registered with the GST portal. Pass the received OTP to file_gstr1().
Args: access_token: Taxpayer session token pan: Permanent Account Number associated with the GSTIN (e.g. "ABCCQ3123E")
Returns: Dict with OTP generation status, or an error dict.
Inputs: pan (required), access_token (required). Returns: result
generate_taxpayer_sessionA
Generate a taxpayer session (access token) valid for 6 hours.
This is Step 1 of the GSTR-1 filing workflow. The returned access_token must be passed to all subsequent tool calls.
Args: gstin: 15-digit GST Identification Number (e.g. "29AAACQ3770E000") username: GST portal username of the taxpayer
Returns: Dict with access_token and session metadata, or an error dict.
Inputs: gstin (required), username (required). Returns: result
get_gstr1_summaryA
Retrieve the GSTR-1 summary including sec_sum and chksum needed for filing (Step 5).
The sec_sum and chksum values returned here must be passed directly to file_gstr1().
Args: access_token: Taxpayer session token gstin: 15-digit GST Identification Number ret_period: Return period in MMYYYY format summary_type: "long" for full section detail (default), "short" for totals only
Returns: Dict with sec_sum array and chksum string, or an error dict.
Inputs: gstin (required), ret_period (required), access_token (required), summary_type. Returns: result
proceed_to_fileA
Initialise the filing process after data validation is complete (Step 4).
Poll check_return_status() with the returned reference_id until COMPLETED before calling get_gstr1_summary().
Args: access_token: Taxpayer session token gstin: 15-digit GST Identification Number ret_period: Return period in MMYYYY format is_nil: "Y" for a nil return, "N" for a regular return (default "N")
Returns: Dict with reference_id for status polling, or an error dict.
Inputs: gstin (required), ret_period (required), access_token (required), is_nil. Returns: result
save_gstr1_dataA
Upload GSTR-1 data to the GST portal for validation (Step 2).
After calling this tool, use check_return_status() with the returned reference_id to poll until the status is COMPLETED before proceeding.
Args: access_token: Taxpayer session token from generate_taxpayer_session() gstin: 15-digit GST Identification Number ret_period: Return period in MMYYYY format (e.g. "032026" for March 2026) gstr1_data: Complete GSTR-1 payload dict containing b2b, b2cl, b2cs, hsn, docs sections etc.
Returns: Dict with reference_id for status polling, or an error dict.
Inputs: gstin (required), gstr1_data (required), ret_period (required), access_token (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 8 tools
Each tool maps to a distinct step in the GSTR-1 filing workflow. Even the two filing-related tools are clearly separated by validation, polling, and EVC OTP phases, and the only polling tool is explicitly scoped to operation status.
All tool names use a consistent snake_case verb_led pattern: generate_, save_, check_, proceed_to_, get_, file_, convert_. The naming reliably communicates what each tool does without mixing conventions.
Eight tools is well-scoped for this server: seven correspond directly to the filing workflow steps, plus one Excel-to-payload converter. There is no redundant or filler tool.
The surface covers the full end-to-end filing lifecycle: session generation, data upload, status polling, filing initiation, summary retrieval, EVC OTP generation, and final submission. No workflow step is missing, and every flow ends in a usable result or explicit error.
Maintenance
Related MCP Connectors
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Connect ChatGPT and Claude to Fortnox: invoices, customers, reports. Every write needs your OK.
Send invoices from Claude and ChatGPT. One sentence becomes a PDF with a Stripe payment link.
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAutomates FreshBooks invoicing and time tracking through Claude, allowing users to send invoices, list invoices, log billable hours, and get financial insights via natural language commands.2-
- FlicenseNot gradedqualityNot gradedmaintenanceConnects Claude Desktop to GoHighLevel CRM with 269+ tools for complete contact management, messaging, sales pipelines, appointments, e-commerce, invoicing, social media, and marketing automation through natural language.1-
- AlicenseCqualityDmaintenanceConnects Claude AI to Google Sheets for automated revenue tracking, lead management, and business operations, with Gmail and calendar integration.13MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to generate India GST e-invoices (IRN) via Sandbox GSP, computing tax splits automatically.MIT