Skip to main content
Glama
Sandbox GSTR-1 MCP Server

Sandbox GSTR-1 MCP Server

by vishnu27597

Sandbox GSTR-1 MCP Server

License: MIT Python 3.11+ MCP Protocol

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

  1. Clone the repository:

    git clone https://github.com/yourusername/sandbox-gstr1-mcp.git
    cd sandbox-gstr1-mcp
  2. Install dependencies:

    pip install -r requirements.txt
  3. Add to Claude Desktop:

    • Open your Claude Desktop configuration file:

      • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

      • Windows: %APPDATA%\Claude\claude_desktop_config.json

      • Linux: ~/.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"
            }
          }
        }
      }
  4. 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.py

Related 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

๐Ÿ”ง 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_ed6b10d21cf546d7b4b600021f91c341

  • API Secret: secret_test_798d3274325741fab93dd24bbb786a3a

  • Environment: 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.py

Expected 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

git clone https://github.com/yourusername/sandbox-gstr1-mcp.git
cd sandbox-gstr1-mcp
pip install -r requirements.txt

Method 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.txt

Method 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

  1. Verify configuration file path is correct

  2. Check Python path is accessible

  3. Ensure all dependencies are installed

  4. Restart Claude Desktop completely

  5. Check Claude logs for errors

API Connection Errors

  1. Verify API key is correct

  2. Check internet connectivity

  3. Confirm API URL is correct

  4. 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:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Write tests

  5. Submit a pull request

๐Ÿ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

๐Ÿ”— Resources

๐Ÿ“ž Support

For issues or questions:

  1. Check the troubleshooting guide

  2. Review the documentation

  3. Check examples

  4. 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 tools
check_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

    A4.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers