🇮🇳 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
• Tech Stack
• Architecture Diagram
• Demo & Links
• Key Features
• Quick Start
• Tool Catalog
• Agent Workflows & Resources
• Data Architecture & Freshness
• Limitations
• Legal & Attribution
• Launch Notes

📌 Problem Statement

• Fragmented Access: Indian fintech, identity, and tax APIs are heavily siloed, requiring multiple disjointed integrations.
• High Barriers to Entry: Existing solutions are plagued by paid subscriptions, strict rate limits, and complex API key management.
• No Native AI Integration: There is no MCP-native standard designed specifically for autonomous AI agents to validate GSTIN, PAN, IFSC, or compute tax data.
• Latency & Reliability Issues: Depending on remote third-party APIs for static/slow-moving datasets introduces unnecessary network delays and potential points of failure for AI workflows.

🛠️ Tech Stack

🏗️ Architecture Diagram

MCP Client ↔ MCP Server ↔ 76 offline-first tool modules

🔗 Demo & Links

• Demo Video: https://youtu.be/KAy6043Co0w?si=FIFfVRM2y3Zwv8oK
• Deployment: https://pypi.org/project/mcp-india-stack/
• PPT: https://gamma.app/docs/Problem-India-lacks-native-fintech-primitives-for-AI-agents-d1izzfemlvfvkf0?mode=doc
• GitHub: https://github.com/rehan1020/MCP-India-Stack
• PyPI: https://pypi.org/project/mcp-india-stack/

✨ 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: 76 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

📈 Stock Market

• get_stock_quote — Fetch live/delayed Indian stock quotes and summaries (NSE/BSE) using yfinance.
• get_stock_history — Fetch historical end-of-day data for Indian stocks using yfinance.

⚖️ Legal Reference

• decode_cnr_number — CNR (Case Number Record) decoder and validator
• lookup_court_establishment_code — Court establishment code directory lookup
• lookup_ipc_section — IPC section lookup with BNS crosswalk
• lookup_bns_section — BNS section lookup with IPC crosswalk
• lookup_crpc_section — CrPC section lookup with BNSS crosswalk
• lookup_bnss_section — BNSS section lookup with CrPC crosswalk
• lookup_evidence_act_section — Indian Evidence Act section lookup
• lookup_bsa_section — BSA section lookup with IEA crosswalk
• decode_ipc_bns_crosswalk — Bidirectional IPC↔BNS section crosswalk
• calculate_limitation_deadline — Limitation Act 1963 deadline calculator
• calculate_court_fee — State-wise court fee calculator
• calculate_stamp_duty — State-wise stamp duty and registration fee calculator

📋 RTI Toolkit

• calculate_rti_fee — RTI application fee calculator (central + state)
• calculate_rti_deadline — RTI response and appeal deadline calculator
• calculate_rti_penalty_estimate — RTI penalty estimator (Section 20)
• draft_rti_application — RTI application drafter (Section 6)
• draft_first_appeal — First appeal template generator (Section 19)
• draft_second_appeal — Second appeal template generator (Section 19)

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

See LEGAL_NOTICE.md for important legal disclaimers including:

• No Government Affiliation — This project is not affiliated with NIC, eCourts, MeitY, or any government body.
• Not Legal Advice — All outputs (bare-act lookups, limitation calculations, court fee estimates, stamp duty estimates, RTI deadline/penalty calculations) are algorithmic estimates, not legal advice.
• Data Accuracy — State-subject data (court fees, stamp duty) carries as_of / last_verified fields and is not live-verified against issuing authorities.
• Personal Data — Identity validation (Aadhaar, PAN, etc.) is structural/checksum only. Users are responsible for DPDP Act compliance.

🚀 Launch Notes

This repository is release-ready for GitHub launch with:

• 0.6.0 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.

New in v0.6.0 — Legal Reference & RTI Toolkit

• Legal Reference: CNR decoder, court establishment lookup, bare-act section lookups (IPC/BNS/CrPC/BNSS/IEA/BSA), IPC↔BNS crosswalk, limitation period calculator, court fee calculator (10 states), stamp duty calculator (10 states).
• RTI Toolkit: RTI fee calculator, deadline tracker, penalty estimator, application/appeal template drafters.
• Capital Gains: Updated LTCG exemption from ₹1L to ₹1.25L (Budget 2024).
• Stock Market: Added yfinance-based get_stock_quote and get_stock_history tools.

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.