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