MCP-India-Stack

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

GitHub
87

Documentation

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

PyPI version License: MIT MCP Compatible CI Verified on MseeP MseeP.ai Security Assessment Badge

📑 Table of Contents

📌 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

LayerTechnology
ProtocolMCP (FastMCP)
RuntimePython
DistributionPyPI / Smithery
HostingRender
DatasetsOffline-bundled (jsDelivr CDN sync)

🏗️ 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

✨ 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

✅ Validation Tools

📱 Identity & Contact

⚡ Bulk Operations

🧮 Tax & Financial Calculators (FY2025-26)

💰 Savings & Investment Calculators

🏠 Real Estate

💼 HR & Payroll

🏦 Banking & Payments

📈 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

📋 RTI Toolkit

🔐 Account Aggregator (Offline)

🔄 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):

Network TierPolicyTool CountTools Included
none (Network: None)Pure offline execution. Zero network calls, zero external endpoints, no sockets opened. Computations, format checks, checksum algorithms, and tax rules execute entirely in-process using local logic.73validate_gstin, bulk_validate_gstin, validate_pan, bulk_validate_pan, decode_pan_type, validate_upi_vpa, decode_state_code, validate_aadhaar, bulk_validate_aadhaar, validate_voter_id, validate_driving_license, validate_passport, validate_cin, validate_din, validate_fssai, validate_tan, validate_mobile_number, validate_pran, validate_llpin, decode_isin, lookup_bank, lookup_bbps_biller, validate_epf_code, validate_esic_code, decode_digilocker_uri, verify_einvoice_qr, verify_aadhaar_offline_artifact, build_aa_consent_request, validate_aa_consent_artifact, decode_aa_fi_type, calculate_income_tax, calculate_tds, calculate_surcharge, calculate_hra_exemption, calculate_capital_gains, calculate_advance_tax, calculate_epf_esic, calculate_emi, calculate_gratuity, calculate_ppf_maturity, calculate_fd_maturity, calculate_rd_maturity, calculate_sip_returns, calculate_step_up_sip, calculate_nps_projection, calculate_sukanya_samriddhi, calculate_home_vs_rent, calculate_gst_late_fee, calculate_income_tax_interest, calculate_presumptive_tax, calculate_professional_tax, calculate_leave_encashment_tax, calculate_salary_restructuring, calculate_neft_rtgs_imps_charges, get_regulatory_deadlines, decode_cnr_number, lookup_court_establishment_code, lookup_ipc_section, lookup_bns_section, lookup_crpc_section, lookup_bnss_section, lookup_evidence_act_section, lookup_bsa_section, decode_ipc_bns_crosswalk, calculate_limitation_deadline, calculate_court_fee, calculate_stamp_duty, calculate_rti_fee, calculate_rti_deadline, calculate_rti_penalty_estimate, draft_rti_application, draft_first_appeal, draft_second_appeal
optional (Network: Optional)Datasets are bundled locally offline (IFSC master, postal pincodes, HSN/SAC master). When enabled, background non-blocking CDN refresh or optional live lookup enriches local data. If network is unavailable or blocked, falls back seamlessly to bundled local datasets without blocking or error.5lookup_ifsc, bulk_validate_ifsc, lookup_pincode, lookup_hsn_code, calculate_gst
required (Network: Required)Live financial market data feeds. Must reach market upstream endpoints (e.g. Yahoo Finance) to retrieve current quotes or historical prices. If network is blocked or unavailable, returns structured error envelopes without unhandled exceptions.2get_stock_quote, get_stock_history