🇮🇳 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
• Authenticity System
• 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 Clients                        |
|       (Claude Desktop, Cursor, Custom Agent Frameworks)   |
+-----------------------------+-----------------------------+
                              |
                     STDIO / SSE Protocol
                              |
+-----------------------------v-----------------------------+
|                      MCP India Stack                      |
|                     (FastMCP Server)                      |
+-----------------------------+-----------------------------+
                              |
      +-----------------------+-----------------------+
      |                       |                       |
+-----v-------------+  +------v------------+  +-------v-----+
| Pure Offline (71) |  |   Offline + CDN   |  |   Market    |
| Format Validators |  |   Refresh (5)     |  |  Data (2)   |
| Tax Calculators   |  | IFSC, HSN, Pin    |  |  yfinance   |
| Legal Reference   |  | Bundled Datasets  |  |  Delayed    |
+-------------------+  +-------------------+  +-------------+

MCP Client ↔ FastMCP Server ↔ 78 modular tool endpoints

🔗 Links

• Deployment: docs/deployment.md
• 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: 80 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.

🛡️ Authenticity System

Every verifying tool states how strongly an identifier is attested through standard levels (A0 to A4) instead of a simplistic binary flag:

• A0 (Format & Checksum): Structural syntax and checksum algorithms pass offline (e.g. Luhn mod-36 for GSTIN, Verhoeff for Aadhaar).
• A1 (Cross-Field Consistency): Cross-field rules pass offline (e.g. embedded PAN in GSTIN, ROC jurisdiction in CIN, RTO code in DL).
• A2 (Authoritative Dataset Match): Record matched in a bundled authoritative dataset (e.g. RBI IFSC directory, India Post pincode list, NSDL ISIN list).
• A3 (Cryptographic Artifact Verification): Digital signature on a supplied artifact verified offline (e.g. NIC e-invoice QR code, UIDAI offline XML).
• A4 (Live Registry Attestation): Confirmed via an opt-in live registry provider.

Every response includes an additive authenticity object with verified checks, authority source, evaluation date, and explicit limitations (e.g. "active registration status not verified"). See docs/authenticity.md and docs/writing_a_provider.md for complete details.

🚀 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
• verify_einvoice_qr — Cryptographically verify NIC B2B e-invoice signed QR codes (A3 Authenticity)
• verify_aadhaar_offline_artifact — Cryptographically verify UIDAI Paperless Offline e-KYC XML/ZIP (A3 Authenticity)

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

All datasets are bundled directly within the package and checksum-verified at build time:

• Offline First: Zero runtime network calls for dataset queries. No external CDN dependency or cache shadowing.
• Deterministic: Data freshness is tied to package releases. To receive updated datasets, upgrade mcp-india-stack.
• Integrity: Bundled dataset integrity is verified against a build-time SHA-256 manifest.

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

What's New in v0.8.0 — Authenticity System (A0-A4), Signed Datasets & Cryptographic Verification

• Multi-Tier Authenticity System (8a): Every verifying tool outputs an additive authenticity envelope (A0 to A4) enforcing rules R1–R6.
• Signed Dataset Manifests (8b): Detached Ed25519 dataset verification, key ring with rotation/revocation, monotonic anti-rollback checks, and --verify-data CLI command.
• Cryptographic Artifact Verification (8c): Signed NIC B2B e-invoice QR code verification and UIDAI secure offline XML/ZIP e-KYC attestation with XXE/bomb defense.
• Opt-In Registry Provider Interface (8d): Pluggable BaseRegistryProvider(ABC) with entry points discovery, FixtureProvider, circuit breaker, rate limiting, and SSRF defense.

Previous Releases

• v0.6.0: Legal Reference (CNR decoder, court establishment lookup, bare-act section lookups for IPC/BNS/CrPC/BNSS/IEA/BSA, IPC↔BNS crosswalk, limitation period calculator, court fee, stamp duty) and RTI Toolkit (fee calculator, deadline tracker, penalty estimator, templates). Added yfinance-based market data tools.
• v0.4.x: Deep statutory audit across capital gains thresholds, EPF wage ceilings, metro HRA rules, 7-slab presumptive tax, and GST late fee caps. See CHANGELOG.md for detailed history.

Offline-First Guarantee

The package classifies every tool under an authoritative network access attribute (none, optional, or required), surfaced programmatically in the india://status MCP resource (tools_network):