ato-mcp

mcp-name: io.ausdata/ato-mcp

MCP server for Australian Taxation Office statistics. Plain-English access to personal tax by postcode, company tax by industry, corporate tax transparency for every $100M+ entity, super contributions by age, salary by occupation, monthly GST collections, and the live ACNC charity register — all from a single uvx command.

Hosted access? For cross-source queries, webhooks, an always-on REST API, and a uniform response envelope across all 9 sources, see ausdata.io — free tier available (500 calls/mo, no card).

"What's the median taxable income in postcode 2000?"
"How much tax did BHP pay last year?"
"Which industries have the highest gross income?"
"How many Large charities are there in NSW?"
"What's the average super contribution for under-30s in the top tax bracket?"

Sister to abs-mcp (Australian Bureau of Statistics), rba-mcp (Reserve Bank of Australia), and au-weather-mcp (Australian weather via Open-Meteo + BOM). The four together cover the macro / regulator / tax / climate layer of Australian official data.

Install

# Run on demand via uvx (recommended)
uvx --upgrade ato-mcp

# Or install permanently
pip install ato-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ato": { "command": "uvx", "args": ["--upgrade", "ato-mcp"] }
  }
}

Why --upgrade? uvx ato-mcp (without the flag) uses whatever wheel is cached and never adopts new PyPI releases on its own. --upgrade makes uvx check PyPI on each launch and pull a newer release if one exists. To verify which version is currently serving you, look at the server_version field on any DataResponse.

Claude Code / Cursor

claude mcp add ato --command uvx --args -- --upgrade ato-mcp

Auto-updating data

Beyond the wheel-level --upgrade, the server has a second auto-update path inside the data layer: when ATO publishes Taxation Statistics 2023-24 next year, ato-mcp resolves the new resource URL via data.gov.au's CKAN API at fetch time and uses the freshest match. Hard-coded YAML URLs are the safe fallback if discovery fails. You do not need to wait for a new wheel release to get new yearly data — just delete ~/.ato-mcp/cache.db to force a refresh, or wait for the 7-day TTL to expire.

What it exposes

Seven tools, all plain-English in, structured out:

Every response is the same shape — dataset_id, dataset_name, query, period, unit, row_count, records, ato_url, attribution, server_version — across every curated dataset.

Curated datasets (14)

Adding a new dataset is a single YAML drop into src/ato_mcp/data/curated/ — see CONTRIBUTING.md.

Example queries (paste into Claude)

Cross-source compatibility. All location filters accept canonical state codes ("NSW"), full names ("New South Wales"), case-insensitive variants ("nsw"), ISO 3166-2 ("AU-NSW"), and 4-digit postcodes ("2000" → NSW) on the state filter. Powered by aus-identity — the same input shape works across abs-mcp, ato-mcp, apra-mcp, aihw-mcp, and asic-mcp.

Property-tech: "For postcodes 2000, 2008, 2026, and 2031 in NSW, give me the median taxable income across every available year so I can compare trajectories."

Corporate tax: "Get the total income, taxable income, and tax payable for BHP IRON ORE (JIMBLEBAR) PTY LTD."

Industry analysis: "Which fine industry codes under 'C. Manufacturing' have the highest total income, and how many companies are in each?"

Charity/non-profit tech: "Find every charity in NSW with size 'Large' that operates_in_VIC = Y."

Retirement planning: "What's the average personal super contribution for males aged 30-39 in the $120,001–$180,000 bracket?"

Each prompt resolves to one get_data call. The response includes the source URL so the agent can cite it back.

Architecture

Same shape as the sister packages — client → cache → parsing → shaping → server:

• client.py wraps httpx with a SQLite-backed disk cache (per-resource TTL).
• parsing.py reads XLSX (via openpyxl/pandas) and CSV (via pandas). Header rows + sheet names live in the curated YAML so future format quirks are a YAML edit, not a code change.
• curated.py loads dataset specs from data/curated/*.yaml — each one declares its dimensions, measures, dimension value enums, source/download URLs, format, and parse layout.
• shaping.py transforms the parsed DataFrame into DataResponse (records / series / csv).
• server.py is the FastMCP entrypoint — seven tools, full input validation with helpful "Try X" hints on error.

Cache lives under ~/.ato-mcp/cache.db. Data on data.gov.au refreshes once a year (ATO) or weekly (ACNC), and the TTLs are tuned for that.

Attribution

Data sourced from the Australian Taxation Office and the Australian Charities and Not-for-profits Commission, both via data.gov.au. Licensed under Creative Commons Attribution 3.0 Australia (CC BY 3.0 AU). The MCP server is MIT-licensed; the data carries the upstream CC-BY 3.0 AU licence, which is echoed in every response's attribution field.

Sister MCPs (Australian Public Data portfolio)