@mountainpass/addressr-mcp

MCP (Model Context Protocol) server for Australian address search and validation powered by Addressr.

Search, validate, and retrieve detailed Australian address data from the Geocoded National Address File (G-NAF), directly from your AI assistant.

How It Works

@mountainpass/addressr-mcp is a thin proxy. The G-NAF dataset (roughly 13 million Australian addresses, see Data Source below) stays on the Addressr API. It never enters the MCP server or your AI client's context window.

What enters context

When your AI client connects:

1. At session start: the tool schemas (the search-*, get-*, and health tools) load once, just a few hundred tokens describing what each tool does.
2. Per tool call: only the matched results come back. A search returns up to 8 candidates with their canonical URLs; a get fetches one record.

The full dataset never enters context. Each call is scoped to the query.

Example flow

Ask: "What's the address ID for 1 George Street, Sydney?"

1. The AI client picks search-addresses and calls it with q="1 george st sydney".
2. The MCP server forwards the query to the Addressr API. The API returns up to 8 ranked matches.
3. The AI client picks the best match and calls get-address with that match's canonical URL.
4. The MCP server returns the full record (geocoding, structured components, confidence score).

Context footprint across the whole flow: tool schemas + up to 8 search results + 1 full address record. The dataset stays on the server.

For the response shape and HATEOAS navigation pattern, see Response Format and HATEOAS Workflow below.

Quick Start

1. Get an API Key

Sign up at RapidAPI to get your API key.

2. Configure Your AI Client

Set ADDRESSR_RAPIDAPI_KEY in your environment before starting your AI client. The MCP server inherits it from the parent process.

Claude Desktop

Claude Desktop launched from the Dock or Spotlight does not inherit shell environment variables. Set the key directly in the local config file (never committed):

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "addressr": {
      "command": "npx",
      "args": ["-y", "@mountainpass/addressr-mcp"],
      "env": {
        "ADDRESSR_RAPIDAPI_KEY": "your-rapidapi-key"
      }
    }
  }
}

Claude Code

export ADDRESSR_RAPIDAPI_KEY=your-rapidapi-key
claude mcp add addressr -- npx -y @mountainpass/addressr-mcp

Cursor

Add to .cursor/mcp.json (local config, never committed):

{
  "mcpServers": {
    "addressr": {
      "command": "npx",
      "args": ["-y", "@mountainpass/addressr-mcp"],
      "env": {
        "ADDRESSR_RAPIDAPI_KEY": "your-rapidapi-key"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json (local config, never committed):

{
  "servers": {
    "addressr": {
      "command": "npx",
      "args": ["-y", "@mountainpass/addressr-mcp"],
      "env": {
        "ADDRESSR_RAPIDAPI_KEY": "your-rapidapi-key"
      }
    }
  }
}

Key Safety

The setup snippets above paste your RapidAPI key in plaintext. That is the simplest path, but it has real leak vectors:

• Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json) is user-readable and is typically swept up by OS backups (Time Machine, or iCloud Drive if your Library is synced).
• .cursor/mcp.json and .vscode/mcp.json sit inside your project directory and are easy to commit by accident. If you keep the key there, add the file to .gitignore.
• export ADDRESSR_RAPIDAPI_KEY=... is written to ~/.zsh_history or ~/.bash_history and survives there until pruned.

Pick whichever mitigation you can live with:

1. Skip shell history with a leading space

If your shell ignores space-prefixed commands (setopt HIST_IGNORE_SPACE in zsh, HISTCONTROL=ignorespace in bash), prefix the export:

 export ADDRESSR_RAPIDAPI_KEY=your-rapidapi-key
claude mcp add addressr -- npx -y @mountainpass/addressr-mcp

2. macOS Keychain

Store the key once:

security add-generic-password -s addressr-rapidapi -a "$USER" -w

Load it when starting Claude Code:

export ADDRESSR_RAPIDAPI_KEY=$(security find-generic-password -s addressr-rapidapi -w)
claude mcp add addressr -- npx -y @mountainpass/addressr-mcp

3. 1Password CLI

If you use 1Password, reference the key from a vault with op:// syntax in a committed .env.tpl (secrets stay in 1Password, the template is safe to commit):

ADDRESSR_RAPIDAPI_KEY={{ op://Private/addressr-rapidapi/credential }}

Hydrate at runtime without writing the key to disk:

op run --env-file=.env.tpl -- claude mcp add addressr -- npx -y @mountainpass/addressr-mcp

4. Wrapper script for Claude Desktop / Cursor / VS Code

Clients that cannot inherit shell environment (Claude Desktop launched from the Dock, for example) can be pointed at a wrapper script that loads the key from Keychain or 1Password at launch time, instead of having the key embedded in the config JSON:

{
  "mcpServers": {
    "addressr": {
      "command": "bash",
      "args": ["/absolute/path/to/run-addressr-mcp.sh"]
    }
  }
}

run-addressr-mcp.sh:

#!/usr/bin/env bash
set -e
export ADDRESSR_RAPIDAPI_KEY=$(security find-generic-password -s addressr-rapidapi -w)
exec npx -y @mountainpass/addressr-mcp

Then:

chmod 700 run-addressr-mcp.sh

5. Restrict permissions on any file that does hold the key

chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
chmod 600 .cursor/mcp.json .vscode/mcp.json 2>/dev/null || true

If the key leaks

Rotate it immediately at RapidAPI → My Apps. Deleting the key from a committed file does not remove it from git history, and the key remains valid until you revoke it upstream.

Environment Variables

Variable	Description
ADDRESSR_RAPIDAPI_KEY	Your RapidAPI key (preferred)
RAPIDAPI_KEY	Fallback RapidAPI key
ADDRESSR_API_URL	Override API base URL (default: https://addressr.p.rapidapi.com/)
RAPIDAPI_HOST	Override API host (default: addressr.p.rapidapi.com)

Available Tools

Search Tools

Search tools return an envelope with status, headers, and body. The headers.link field is a parsed array of HATEOAS links ({ uri, rel, anchor?, title? }) that can be followed to retrieve detail resources.

search-addresses

Search Australian addresses by street, suburb, or postcode. Returns up to 8 results per page with standard address format, relevance score, and property ID (PID).

Parameters:

• q (required): Search query, e.g. "1 george st sydney", "2000", "pyrmont nsw"
• page (optional): Page number for paginated results

search-postcodes

Search Australian postcodes by partial text or number. Returns matching postcodes and their associated localities.

Parameters:

• q (required): Search query, e.g. "2000", "200", "sydney"
• page (optional): Page number for paginated results

search-localities

Search Australian localities (suburbs) by name. Returns matching localities with state and postcode.

Parameters:

• q (required): Search query, e.g. "sydney", "melbourne", "pyrmont"
• page (optional): Page number for paginated results

search-states

Search Australian states and territories by name or abbreviation. Returns all matching states.

Parameters:

• q (required): Search query, e.g. "NSW", "New South Wales", "Victoria"
• page (optional): Page number for paginated results

Detail Tools

Detail tools accept a canonical url from search results and return the full resource.

get-address

Get full address details by URL. Follow the canonical link from search results to retrieve geocoding (lat/long), structured components (street, suburb, state, postcode, unit/flat), and confidence score.

Parameters:

• url (required): Canonical URL from search-addresses results, e.g. "https://addressr.p.rapidapi.com/addresses/GANSW710280564"

get-locality

Get full locality details by URL. Follow the canonical link from search results to retrieve structured locality data including name, state, postcode, and class.

Parameters:

• url (required): Canonical URL from search-localities results, e.g. "https://addressr.p.rapidapi.com/localities/GAUTH-12345"

get-postcode

Get full postcode details by URL. Follow the canonical link from search results to retrieve the postcode and associated localities.

Parameters:

• url (required): Canonical URL from search-postcodes results, e.g. "https://addressr.p.rapidapi.com/postcodes/2000"

get-state

Get full state details by URL. Follow the canonical link from search results to retrieve state name and abbreviation.

Parameters:

• url (required): Canonical URL from search-states results, e.g. "https://addressr.p.rapidapi.com/states/NSW"

Utility Tools

health

Check API service status. Returns version, timestamp, and health status.

HATEOAS Workflow

The MCP server is designed around HATEOAS (Hypermedia as the Engine of Application State):

1. Search with a search tool (e.g. search-addresses q="1 george st sydney")
2. Inspect the headers.link array for rel="canonical" links with anchor pointing to result items
3. Follow the canonical URL with the matching detail tool (e.g. get-address url="...")
4. Navigate further using rel="related" links in detail responses

Response Format

All tools return an envelope:

{
  "status": 200,
  "headers": {
    "content-type": "application/json; charset=utf-8",
    "link": [
      { "uri": "/addresses/GANSW710280564", "rel": "canonical", "anchor": "#/0" },
      { "uri": "/addresses?page=1&q=1+george+st+sydney", "rel": "next" }
    ]
  },
  "body": { ... }
}

The body is the raw JSON from the Addressr API. The headers.link array is parsed from the HTTP Link header for machine-readable navigation.

Local Development

Clone the repo and configure Claude Code:

git clone https://github.com/mountain-pass/addressr-mcp.git
cd addressr-mcp
op inject -i .env.tpl -o .env

The .mcp.json in the repo root configures the local server. Claude Code will discover it automatically when started in this directory.

Data Source

Address data is sourced from the Geocoded National Address File (G-NAF), Australia's authoritative address database maintained by Geoscape Australia.

License

Apache-2.0