🇮🇳 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: 30 dedicated tools for identity validation (PAN, Aadhaar, GSTIN), tax calculation (Income Tax, TDS, GST), 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
• 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
• decode_digilocker_uri — DigiLocker URI decoder and validator mapper
• decode_pan_type — Decode PAN entity type from the 4th character

⚡ Bulk Operations

• bulk_validate_gstin — Parallel GSTIN batch validation
• bulk_validate_pan — Parallel PAN batch validation
• bulk_validate_ifsc — Parallel IFSC 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 12+ sections
• calculate_gst — GST breakdown (CGST/SGST/IGST/cess)
• calculate_surcharge — Surcharge and marginal relief calculator
• calculate_hra_exemption — HRA exemption calculator for salary planning
• calculate_capital_gains — Capital gains tax helper
• calculate_advance_tax — Advance tax estimator

---

🔄 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.3.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.