🇮🇳 MCP India Stack

A high-performance, offline-first Model Context Protocol (MCP) server equipping AI agents with Indian financial, tax, and government APIs. Zero authentication required.

📑 Table of Contents

• Problem Statement
• Key Features
• Quick Start
• Tech Stack
• Architecture Diagram
• Tool Catalog
• Agent Workflows & Resources
• Data Architecture & Freshness
• Limitations
• Legal & Attribution
• Team
• Hackathon Track
• Demo & Links
• Launch Notes

📌 Problem Statement

• Fragmented API Landscape: AI agents lack a unified, standard interface to interact with scattered Indian financial, tax, and government systems.
• Authentication Blockers: Traditional APIs require API keys, secrets, or paid subscriptions, making it impossible for autonomous agents to perform zero-setup operations.
• Latency & Reliability Constraints: Calling remote third-party APIs for static/slow-moving datasets introduces unnecessary network delays and points of failure.
• Data Freshness Burden: Manually maintaining local copies of critical validation datasets (like IFSC or HSN codes) is tedious and error-prone.

✨ Key Features

• Offline-First Architecture: Bundles compressed datasets for zero-latency lookups (IFSC, Pincodes, HSN/SAC). No API rate limits.
• Zero Authentication: No API keys, secrets, or subscriptions required. All logic runs locally.
• Background Auto-Updates: Non-blocking CDN fetching ensures your datasets never go stale without impacting request latency.
• Comprehensive Coverage: 58 dedicated tools for identity validation (PAN, Aadhaar, GSTIN, TAN, PRAN), tax calculation (Income Tax, TDS, GST), savings calculators (EPF, PPF, SIP), and master data lookups.
• Enterprise-Ready: Thread-pool accelerated bulk validation tools for processing large batches of vendor or customer data.

🛠️ Tech Stack

🏗️ Architecture Diagram

High-level architecture of the MCP India Stack.

🛠️ Tool Catalog

🔍 Lookup Tools

• lookup_ifsc — Bank branch details from IFSC code
• lookup_pincode — India pincode details and post offices
• lookup_hsn_code — HSN/SAC code lookup by code or keyword
• decode_state_code — GST state code metadata
• lookup_bbps_biller — BBPS biller directory lookup
• lookup_bank — Basic bank master lookup by name or code

✅ Validation Tools

• validate_gstin — GSTIN structure and checksum
• validate_pan — PAN format and entity type decode
• validate_upi_vpa — UPI VPA structure and provider decode
• validate_aadhaar — Aadhaar number with Verhoeff checksum (masked output)
• validate_voter_id — Voter ID (EPIC) format with legacy detection
• validate_driving_license — DL format with state/RTO/year decode
• validate_passport — Indian passport number format
• validate_cin — Company Identification Number with full field decode
• validate_din — Director Identification Number format
• validate_fssai — FSSAI license number validation and decode
• validate_epf_code — EPF establishment code validator
• validate_esic_code — ESIC employer code validator
• validate_tan — TAN validator
• validate_pran — PRAN validator for NPS
• validate_llpin — LLPIN validator
• decode_isin — ISIN decoder with Luhn validation
• decode_digilocker_uri — DigiLocker URI decoder and validator mapper
• decode_pan_type — Decode PAN entity type from the 4th character

📱 Identity & Contact

• validate_mobile_number — Mobile number with operator/circle detection

⚡ Bulk Operations

• bulk_validate_gstin — Parallel GSTIN batch validation
• bulk_validate_pan — Parallel PAN batch validation
• bulk_validate_ifsc — Parallel IFSC batch validation
• bulk_validate_aadhaar — Parallel Aadhaar batch validation

🧮 Tax & Financial Calculators (FY2025-26)

• calculate_income_tax — Old vs new regime comparison with surcharge, rebate, cess
• calculate_tds — TDS rate lookup and computation for 15+ sections
• calculate_gst — GST breakdown (CGST/SGST/IGST/cess) with HSN lookup
• calculate_surcharge — Surcharge and marginal relief calculator
• calculate_hra_exemption — HRA exemption calculator for salary planning
• calculate_capital_gains — Capital gains with Section 54/54F exemption
• calculate_advance_tax — Advance tax estimator
• calculate_gst_late_fee — GST late filing penalty
• calculate_income_tax_interest — Sections 234A/B/C interest
• calculate_presumptive_tax — 44AD/44ADA presumptive tax
• get_regulatory_deadlines — Tax & regulatory compliance calendar

💰 Savings & Investment Calculators

• calculate_epf_esic — EPF/ESIC contribution calculator
• calculate_emi — Loan EMI with amortization schedule
• calculate_gratuity — Gratuity under Payment of Gratuity Act
• calculate_ppf_maturity — PPF maturity projections
• calculate_fd_maturity — Fixed Deposit maturity
• calculate_rd_maturity — Recurring Deposit maturity
• calculate_sip_returns — SIP returns with inflation adjustment
• calculate_step_up_sip — Step-up SIP comparison
• calculate_nps_projection — NPS corpus and pension
• calculate_sukanya_samriddhi — SSY and SCSS calculator

🏠 Real Estate

• calculate_home_vs_rent — Buy vs rent financial comparison
• calculate_leave_encashment_tax — Section 10(10AA) leave encashment

💼 HR & Payroll

• calculate_professional_tax — State-wise professional tax
• calculate_salary_restructuring — Tax-optimized salary restructuring

🏦 Banking & Payments

• calculate_neft_rtgs_imps_charges — Transaction charges

🔐 Account Aggregator (Offline)

• build_aa_consent_request — AA consent request builder
• validate_aa_consent_artifact — AA consent validator
• decode_aa_fi_type — AA FI type decoder

🔄 Agent Workflows & Resources

Prompt Workflows (Overview)

Built-in prompt templates to guide AI agents through complex multi-step tasks:

• vendor_kyc — GSTIN, PAN, and IFSC verification sequence.
• salary_planner — Income, HRA, and optimized take-home salary planning.
• invoice_audit — Cross-referencing GSTINs, HSN codes, and applicable GST rates.

Server Resources (Overview)

Dynamic JSON resources provided directly to the LLM context:

• india://status — Version, DB connectivity, and runtime flags
• india://changelog — Structured changelog resource
• india://schema/* — JSON schemas for all tool outputs

📡 Data Architecture & Freshness

This package bundles static datasets for offline-first workflows (approx. 10-11MB compressed footprint), covering IFSCs, Pincodes, HSN/SAC masters, and curated UPI handles.

An optional auto-update mechanism fetches the latest versions from the jsDelivr CDN in the background:

• Non-blocking: Stale data triggers a background refresh; the current request immediately uses existing cached data to ensure zero latency.
• Opt out: Set the MCP_INDIA_STACK_NO_AUTO_UPDATE=1 environment variable to disable all update checks.
• Manual refresh: Run mcp-india-stack --refresh-all to synchronously refresh all datasets from the CDN.
• Cache location: Platform-specific via platformdirs (e.g., ~/.cache/mcp-india-stack on Linux).

⚖️ Legal & Attribution

See NOTICES for detailed dataset attribution, licensing details, and third-party acknowledgments.

🧠 Team

🏆 Hackathon Track

Track: Work, Finance & Digital Economy

🔗 Demo & Links

• Demo Video: Insert YouTube/Loom Link Here
• Deployment Link: https://pypi.org/project/mcp-india-stack/(#)
• PPT Link: https://gamma.app/docs/Problem-India-lacks-native-fintech-primitives-for-AI-agents-d1izzfemlvfvkf0(#)
• GitHub Repository: https://github.com/rehan1020/MCP-India-Stack

🚀 Launch Notes

This repository is release-ready for GitHub launch with:

• 0.4.2 package metadata and changelog coverage.
• A complete MCP server-card under docs/.well-known/mcp/server-card.json.
• Local setup and publishing steps in SETUP.md.
• Contribution guidance and versioning policy in CONTRIBUTING.md.

Bug fixes in v0.4.2 (Round 2 — Deep Code Audit)

• Capital Gains: Asset-type-specific LTCG thresholds — real estate 24mo, gold/debentures 36mo, crypto always 30% flat.
• EPF/ESIC: Employee EPF correctly capped at ₹15K wage ceiling. Added voluntary_pf_on_actual for VPF.
• HRA: Removed Bangalore/Hyderabad/Pune from metro cities. Only Delhi/Mumbai/Chennai/Kolkata get 50%.
• Presumptive Tax: Full 7-slab new regime coverage with 87A rebate (was truncated at 3 slabs).
• GST Late Fee: GSTR9 cap enforced (0.25% of turnover). Nil return rate corrected to ₹20/day.
• Income Tax Interest: Section 234C uses cumulative paid vs required (not single-quarter).
• Advance Tax: Installments show incremental installment_amount (not confusing cumulative).
• Salary Restructuring: Removed obsolete ₹19,200 conveyance exemption. Standard deduction (₹75K) shown.

Bug fixes in v0.4.1

• Security: Masked Aadhaar number leakage in response fields.
• Validation: Fixed mobile number over-counting digits issue.
• Tax Rules: Corrected Presumptive Tax (44AD/44ADA) thresholds to FY25-26 rules.
• Financial: Fixed Step-up SIP compounding return calculation.
• Data: Added missing HSN codes (8517, 9401, 2523, 3004, 8708) with correct GST rates.
• Professional Tax: Fixed annual total calculations based on correct monthly slabs.
• Income Tax: Fixed 80D deduction cap for senior citizens.
• ISIN: Fixed Luhn checksum multi-digit expansion logic.
• EMI Calculator: Improved error responses to not leak fallback fields on invalid inputs.
• Advance Tax: Added support for overriding internal computations with user-provided tax_liability.

Offline-First Guarantee: All tools in this package work without an internet connection. No API keys required. No data is sent to any external server. All datasets are bundled in the package at install time.

🚀 Quick Start

Installation

pip install mcp-india-stack

Claude Desktop Configuration

Add the following to your claude_desktop_config.json file to enable the India Stack in Claude Desktop:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-india-stack": {
      "command": "python",
      "args": ["-m", "mcp_india_stack"]
    }
  }
}

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json or ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-india-stack": {
      "command": "python3",
      "args": ["-m", "mcp_india_stack"]
    }
  }
}

⚠️ Limitations

• Stateless Validation: GSTIN, Aadhaar, Voter ID, DL, Passport, CIN, and DIN validators check structural formatting and checksums only. They do not verify active registration status with government issuing authorities.
• Algorithmic Constraints: PAN validation is structural; the PAN check character logic is not publicly verifiable.
• Tax Estimates: All tax calculations are algorithmic estimates based on FY2025-26 rules. Actual liability may differ. Always consult a Chartered Accountant.
• Static Rates: HSN/SAC rates are static references and may vary based on specific conditions or new government notifications.