# ato-mcp

> MCP server exposing Australian Taxation Office and ACNC statistics through 7 plain-English tools — per-postcode personal tax, company tax by industry, corporate tax transparency, GST collections, super contributions, charity register, HELP debt, occupation salaries.

ato-mcp is the Australian Taxation Office (ATO) member of the Australian Public Data MCP portfolio. It fetches ATO Taxation Statistics XLSX and the live ACNC charity register from data.gov.au via CKAN — when ATO publishes next year's Taxation Statistics the server resolves the new resource URL at fetch time, no wheel update required.

14 curated datasets cover the high-value publications: postcode-level income, company tax, $100M+ corporate tax disclosures, super contributions by age, GST monthly collections, ACNC charity register with financial detail, HECS/HELP debt, ATO tax-gap estimates, R&D Tax Incentive claims, occupation salaries, SMSF sector, Small Business Benchmarks. ato-mcp has 7 tools instead of the standard 5 — adds `top_n` for ranked queries and `stats` for grouped aggregates (count/sum/mean/median/min/max/stddev with optional `group_by`).

## Documentation

- [README](https://github.com/Bigred97/ato-mcp/blob/main/README.md): Full setup + tool usage + worked example queries
- [CHANGELOG](https://github.com/Bigred97/ato-mcp/blob/main/CHANGELOG.md): Release history
- [PyPI](https://pypi.org/project/ato-mcp/): `uvx --upgrade ato-mcp`

## Tools

- search_datasets(query, limit=10): Fuzzy search the 14 curated ATO/ACNC datasets
- describe_dataset(dataset_id): Schema — filterable dimensions, measure keys with units, source URL
- get_data(dataset_id, filters, measures, start_period, end_period, format): Filtered query
- latest(dataset_id, filters, measures): Most recent observation per measure (mostly returns single-period for ATO wide tables; trims time series like GST_MONTHLY)
- top_n(dataset_id, measure, n=10, filters, direction="top"): Rank rows by a measure server-side
- stats(dataset_id, measure, filters, group_by): Aggregate (count/sum/mean/median/min/max/stddev) optionally partitioned by a dimension — one call instead of N filtered round-trips
- list_curated(): Enumerate the 14 dataset IDs

## Example queries

- "What's the median taxable income in postcode 2000?"
- "How much tax did BHP pay last year?"
- "Top 10 corporate taxpayers in 2023-24"
- "How many Large charities are there in NSW?"
- "Average super contribution for under-30s in the top tax bracket"
- "Monthly net GST since 2022"
- "Compare median income across all NSW postcodes (grouped stats)"
- "Top R&D Tax Incentive claimants in 2022-23"

## Optional

- [Sister MCPs](https://github.com/Bigred97?tab=repositories&q=mcp): Other AU public-data MCPs (ABS, RBA, APRA, AIHW, ASIC, AEMO, weather, WGEA)
- [aus-identity](https://pypi.org/project/aus-identity/): Postcode/state/ABN normalisation — every dataset's `state` and `postcode` filters accept canonical codes, full names, ISO 3166-2, and 4-digit postcodes
