india-pincode-ifsc-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | Host to bind when using streamable-http transport. | 127.0.0.1 |
| MCP_PORT | No | Port to bind when using streamable-http transport. | 8000 |
| IFSC_BASE_URL | No | IFSC service root (the dataset can be self-hosted). | https://ifsc.razorpay.com |
| MCP_TRANSPORT | No | Transport to use: stdio or streamable-http. | stdio |
| PINCODE_BASE_URL | No | India Post PIN service root (for a mirror or proxy). | https://api.postalpincode.in |
| INDIA_LOOKUP_RETRIES | No | Retries on HTTP 429, 502, 503, 504 and timeouts. | 2 |
| INDIA_LOOKUP_TIMEOUT | No | Request timeout in seconds. | 20 |
| INDIA_LOOKUP_MAX_CHARS | No | Responses longer than this are cut with a notice. | 20000 |
| INDIA_LOOKUP_CONCURRENCY | No | Parallel upstream requests for bulk lookups. | 5 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Indian address and banking reference data from two free public services: India Post (PIN codes and post offices) and the Razorpay IFSC dataset (bank branches). Use lookup_pincodes to validate PIN codes and get state, district and post offices; search_post_offices to find the PIN for a locality name; lookup_ifsc to verify an IFSC and get the branch, address and payment services (optionally cross-checked with the postal area of its PIN); search_ifsc to list branches of a bank in a city. India only. Read-only, no credentials.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| lookup_pincodesA | Validate and look up 1 to 25 Indian PIN codes in one call. Each match returns state, district, division, region, postal circle and the post offices under that PIN with their type (HO head, SO sub, BO branch office) and whether they deliver mail. PINs that are not 6 digits are reported under 'invalid_format' without a request; well-formed PINs that India Post does not know are under 'not_found'. detail='full' adds each office's block and raw fields. Use search_post_offices when you only have a locality name. |
| search_post_officesA | Find Indian post offices by name (locality, town or office name) and get each one's PIN code, type, delivery status, district and state. Names repeat across India (there are many 'Gandhi Nagar'), so check district and state. Use it to go from a place name to a PIN code; use lookup_pincodes to go from a PIN to its area. |
| lookup_ifscA | Verify and look up 1 to 25 bank IFSC codes in one call (any case or spacing). Each match returns bank, branch, address, city, district, state, phone, MICR, SWIFT and which payment services the branch supports (NEFT, RTGS, IMPS, UPI), plus the PIN code found in the address. Set with_postal_area=true to also look up that PIN with India Post and return its district, state and post offices, which is a quick check that the branch address is consistent. Malformed codes are listed under 'invalid_format' without a request; unknown ones under 'not_found'. |
| search_ifscA | List bank branches and their IFSC codes, filtered by bank, city and/or branch name (at least one filter). 'bank' accepts a 4-letter bank code or a well-known name such as 'HDFC Bank', 'SBI' or 'Kotak'. City and branch names are matched exactly as the dataset spells them (for example 'MUMBAI', 'SAROJINI NAGAR'), so an unlisted spelling returns nothing. Results are paged: when more exist the reply has next_offset to pass back as offset. For one known IFSC use lookup_ifsc. |
| list_bank_codesA | List the 4-letter IFSC bank codes this server knows by name (about 45 larger banks), optionally filtered by text. Use it to find the code for search_ifsc; any other bank's code is the first 4 characters of its IFSC codes. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 5 tools
The two lookup tools (PIN→area, IFSC→branch) and the two search tools (locality→PIN, bank/city→IFSC) are explicit inverses, and each description names the sibling tool it should not be confused with. list_bank_codes is a narrow helper that feeds search_ifsc, and its role is stated clearly.
All five tools follow a strict verb_noun snake_case pattern (lookup_pincodes, search_post_offices, lookup_ifsc, search_ifsc, list_bank_codes). The verb choice is semantically meaningful: lookup for exact-key resolution, search for filtered discovery, list for enumeration.
Five tools is exactly right for a two-domain (India Post PIN + bank IFSC) lookup server, with two tools per domain plus one small enumerator for bank codes. No tool feels redundant or padded.
Both directions of both domains are covered (key→record, name→key), including batch lookup, validation, and paging on search_ifsc. Minor gaps: no way to enumerate post offices or branches purely by district/state, and no reverse IFSC-from-bank-name-and-branch beyond the filter-based search_ifsc.