mcp-india-stack 0.4.2

MCP server exposing Indian financial and government APIs — GSTIN, IFSC, PAN, UPI, pincode, HSN/SAC — for AI agents. Zero auth. Offline-first.

🇮🇳 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.

✨ 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.

---

🚀 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"]
    }
  }
}

---

🛠️ 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).

---

⚠️ 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.

---

⚖️ Legal & Attribution

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

---

🚀 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.