Australian Postcodes MCP

🚀 Australian Postcodes MCP Server

A high-performance MCP (Model Context Protocol) server providing Australian postcode and suburb data with intelligent fuzzy matching, tailored for AI assistants in customer service interactions.

🚀 Quick Start

📦 Installation

# Clone the repository
git clone https://github.com/yourusername/australian-postcodes-mcp.git
cd australian-postcodes-mcp

# Install dependencies
pip install -r requirements.txt

# Import postcode data
python src/utils/data_loader.py

# Test locally
fastmcp dev src/server.py

Usage with Claude Desktop

Add to your Claude Desktop configuration:

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

✨ Features

🔍 Core Search Capabilities

• Postcode to Suburbs: Retrieve all suburbs associated with a given postcode.
• Suburb to Postcodes: Find postcodes for suburbs, including fuzzy matching.
• Smart Validation: Verify the validity of suburb - postcode combinations.
• LGA Queries: List all suburbs within a Local Government Area (city/council).

🎯 AI - Optimized Features

• Fuzzy Matching: Handle typos and misspellings with confidence scoring.
• Phonetic Search: Match spoken names that might be misheard.
• Autocomplete: Suggest completions for partial suburb names.
• Smart Suggestions: Provide alternatives when exact matches are not found.
• Geographic Search: Find nearby suburbs within a specified radius.

📊 Data Coverage

• Approximately 17,000 Australian postcodes and suburbs.
• Local Government Areas (LGAs).
• Statistical Areas (SA3/SA4).
• Geographic coordinates (latitude/longitude).
• Electoral divisions.
• State and region information.

💻 Usage Examples

🔍 Basic Usage

# Find suburbs for postcode 2300
result = await search_by_postcode("2300")
# Returns: Newcastle, Newcastle West, etc.

# Find postcode for suburb
result = await search_by_suburb("Newcastle", state="NSW")
# Returns: 2300

🎯 Advanced Usage

# Handle misspellings
result = await find_similar_suburbs("Newcaslte", state="NSW")
# Returns: Newcastle (confidence: 0.92), New Lambton (confidence: 0.75)

# Phonetic search
result = await phonetic_search("new castle")
# Returns: Newcastle, Newcastle West

🏙️ LGA Queries

# List suburbs in Newcastle LGA
result = await list_suburbs_in_lga("Newcastle", state="NSW")
# Returns: All suburbs in Newcastle city council area

📚 Documentation

Available Tools

Search Tools

• search_by_postcode - Find suburbs for a given postcode.
• search_by_suburb - Find postcodes for a given suburb.
• validate_suburb_postcode - Verify the validity of a suburb - postcode combination.
• get_location_details - Perform a smart search by accepting either a postcode or a suburb.

Fuzzy Matching Tools

• find_similar_suburbs - Find the closest matches for misspelled suburbs.
• autocomplete_suburb - Get completions for partial suburb names.
• validate_spelling - Suggest spelling corrections.
• phonetic_search - Handle potentially misheard spoken names.

Location Tools

• list_suburbs_in_lga - List all suburbs in a Local Government Area.
• find_lga_for_suburb - Get the Local Government Area (city) for a given suburb.
• list_suburbs_in_radius - Find nearby suburbs within a specified radius.
• get_neighboring_suburbs - Find adjacent areas.

Analytics Tools

• get_state_statistics - Get postcode and suburb counts by state.
• list_all_lgas - List all available Local Government Areas.
• search_by_region - Query by statistical area.

🚀 Deployment

FastMCP Cloud (Recommended)

1. Push your code to GitHub.
2. Connect your repository at fastmcp.cloud.
3. Configure environment variables.
4. Deploy with a single click.

Local Development

# Run development server
fastmcp dev src/server.py

# Run production server
python src/server.py

📄 Data Source

Data is sourced from the community - maintained Australian Postcodes repository.

🔧 Technical Details

• Utilizes SQLite with optimized indexes for fast queries.
• Achieves sub - 100ms response time for most queries.
• Implements efficient fuzzy matching using the rapidfuzz library.
• Caches phonetic encodings for voice queries.

🤝 Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for guidelines.

📄 License

This project is under the MIT License. See LICENSE for details.

🛠️ Support

For issues or questions, please open an issue on GitHub or contact the maintainers.

Built with FastMCP for the Model Context Protocol