Australian Postcodes

FastMCP server for Australian postcodes and suburbs lookup with fuzzy matching

python

5

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jezweb-australian-postcodes-mcp": {
      "command": "fastmcp",
      "args": [
        "run",
        "/path/to/australian-postcodes-mcp/src/server.py"
      ]
    }
  }
}

This MCP server delivers Australian postcode and suburb data with smart search features, enabling fast, accurate responses for customer service and AI assistants. It combines postcode-to-suburb lookups, fuzzy and phonetic search, autocomplete, radius-based geography, and sensible fallbacks to help users quickly find the right location information.

How to use

You connect to the MCP server with an MCP client and issue a range of location-focused queries. Typical tasks include finding all suburbs for a given postcode, locating postcodes for a suburb, validating suburb–postcode pairs, and listing all suburbs within a Local Government Area (LGA). You can also leverage fuzzy matching and phonetic search to handle typos or misheard names, and use geographic search to discover nearby suburbs within a radius.

Common queries you can perform include:

For example, you can use fuzzy or phonetic search to handle misspellings or misheard names, and you can request autocomplete suggestions when you start typing a suburb. If an exact match isn’t found, the system will offer smart alternatives to help you stay productive.

How to install

Prerequisites: ensure you have Python installed and a working internet connection. You will also use the FastMCP command-line tool to run the local MCP server.

Step-by-step installation and setup you can follow locally:

Clone or download the project, then install dependencies and import the data used by the server.

Install Python dependencies from the requirements file

Import postcode data into the runtime environment

Test locally with the runtime command to start a development MCP server

Run the local server in development mode using FastMCP

Alternatively, run the production server directly with Python

Notes

Deployment can be done via FastMCP Cloud or locally. FastMCP Cloud provides a streamlined workflow to publish and manage the MCP server, while local development uses the standard Python runtime and the FastMCP toolchain for testing.

Available tools

search_by_postcode

Find suburbs associated with a given postcode. Returns all matching suburbs for the specified postcode.

search_by_suburb

Find postcodes associated with a given suburb, optionally filtered by state or region.

validate_suburb_postcode

Verify that a suburb and postcode pairing is valid and exists in the dataset.

get_location_details

Smart search that accepts either a postcode or a suburb and returns relevant location details.

find_similar_suburbs

Suggest closest suburb matches for misspelled inputs with confidence scores.

autocomplete_suburb

Provide completions for partial suburb names to speed up data entry.

validate_spelling

Suggest spelling corrections for suburb names based on the dataset.

phonetic_search

Handle phonetic variations of suburb names to account for mishearing.

list_suburbs_in_lga

Return all suburbs within a specified Local Government Area.

find_lga_for_suburb

Identify the LGA or city for a given suburb.

list_suburbs_in_radius

Find suburbs within a geographic radius of a given location.

get_neighboring_suburbs

Retrieve suburbs that are adjacent or in close proximity to a given suburb.

get_state_statistics

Provide counts of postcodes and suburbs grouped by state.

list_all_lgas

List all available Local Government Areas in the dataset.

search_by_region

Query data by statistical region or SA3/SA4 areas.