ato-mcp
This MCP server provides plain-English access to Australian Taxation Office (ATO) and Australian Charities and Not-for-profits Commission (ACNC) statistics and registers via 7 tools and 14 curated datasets.
Tools:
search_datasets— fuzzy-search the catalog by keyword (e.g. "postcode tax", "charity register").list_curated— enumerate all curated dataset IDs.describe_dataset— inspect filterable dimensions, valid filter values, measures, units, and source URLs before querying.get_data— query datasets with filters, measure selection, period ranges, and output format (records, series, CSV).latest— retrieve the most recent observations per measure.top_n— return the top or bottom N rows by a measure (e.g. top corporate taxpayers).stats— compute aggregate statistics (count, sum, mean, median, min, max, stddev), optionally grouped by a dimension.
Curated datasets include: personal tax by postcode, median income by postcode over time, company tax by industry, corporate tax transparency, superannuation contributions by age, ACNC charity register, monthly GST collections, occupation income, SMSF funds, small business benchmarks, HELP debt, tax gaps, R&D tax incentive, and ACNC financials.
Example use cases: look up median taxable income by postcode; find tax paid by a named corporation; rank industries by income; filter charities by state or size; analyze super contributions by age and income; retrieve monthly GST collections; compare salary by occupation and sex; investigate R&D tax incentive claims.
Key features: auto-updating data with a 7-day cache TTL and force refresh; cross-source location filters accept state codes, full names, ISO codes, and postcodes; hosted access at ausdata.io is available for cross-source queries, webhooks, and a REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ato-mcp What's the median taxable income in postcode 2000?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpClaude 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.--upgrademakes uvx check PyPI on each launch and pull a newer release if one exists. To verify which version is currently serving you, look at theserver_versionfield on anyDataResponse.
Claude Code / Cursor
claude mcp add ato --command uvx --args -- --upgrade ato-mcpRelated MCP server: ausdata-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:
Tool | Purpose |
| Fuzzy-search the curated catalog by keyword |
| List a dataset's filterable dimensions and returnable measures |
| Query with |
| Last observation per measure (shortcut) |
| Rank rows by a measure, return top (or bottom) N |
| Aggregate stats (count, sum, mean, median, min, max, stddev) over a measure — optional |
| Enumerate the curated dataset IDs |
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)
ID | What it is | Period | Coverage |
| Personal tax stats by taxable status × state × SA4 × postcode (~5,200 postcodes) | 2022-23 | 80+ measures |
| Median & average taxable income by postcode, every year | 2003-04 → 2022-23 | 21 yearly measures |
| Company tax by ANZSIC broad + fine industry | 2022-23 | 216 industry cells |
| Entity-level tax disclosure for $100M+ corporations (name, ABN, income, tax) | 2023-24 | ~4,200 entities |
| Super contributions by age × sex × taxable income bracket | 2022-23 | Employer/personal/other |
| Live register of every Australian charity (ABN, size, jurisdiction, beneficiaries) | Current (weekly) | ~60,000 entities |
| Monthly GST / WET / LCT collections (gross GST, input tax credits, net GST, etc.) | 2020-07 → 2024-06 | 10 metrics × 48 months |
| Median/average income (taxable, salary/wage, total) by ANZSCO occupation × sex | 2022-23 | ~1,200 jobs × 7 measures |
| SMSF sector size — total funds, total members, total gross assets (trillion-$ sector) | 2019-20 → 2024-25 | 3 metrics × 6 years |
| Industry total-expense + COGS ratio bands by turnover bracket (~100 industries) | 2023-24 | 12 measures × 100 industries |
| HECS/HELP outstanding debt, indexation, compulsory + voluntary repayments annual | 2005-06 → 2024-25 | 8 measures × 20 years |
| ATO's tax gap estimates — how much tax is being missed each year by tax type | 2016-17 onward | 5 measures × 4 tax types × ~7 years |
| R&D Tax Incentive transparency — every entity's R&D claim (name, ABN, $) | 2022-23 | ~13,000 entities |
| Per-charity financials from the ACNC Annual Information Statement (revenue, expenses, staff) | 2023 | ~60,000 charities × 23 measures |
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 thestatefilter. Powered byaus-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.pywrapshttpxwith a SQLite-backed disk cache (per-resource TTL).parsing.pyreads XLSX (viaopenpyxl/pandas) and CSV (viapandas). Header rows + sheet names live in the curated YAML so future format quirks are a YAML edit, not a code change.curated.pyloads dataset specs fromdata/curated/*.yaml— each one declares its dimensions, measures, dimension value enums, source/download URLs, format, and parse layout.shaping.pytransforms the parsed DataFrame intoDataResponse(records / series / csv).server.pyis 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)
Want all 9 sources behind one REST API? The hosted gateway at ausdata.io adds cross-source joins, full history, webhooks, and HMAC-signed responses on top of these MCPs — free tier (500 calls/mo, no card).
abs-mcp — Australian Bureau of Statistics (CPI, unemployment, ERP, building approvals)
rba-mcp — Reserve Bank of Australia (cash rate, lending stats, exchange rates)
ato-mcp — this one. Tax, super, and charity registers.
apra-mcp — Australian Prudential Regulation Authority (banking, insurance, super)
aihw-mcp — Australian Institute of Health and Welfare
asic-mcp — Australian Securities and Investments Commission (company registers)
aemo-mcp — Australian Energy Market Operator (NEM dispatch, spot prices, generation)
au-weather-mcp — Open-Meteo (Bureau of Meteorology aggregator)
wgea-mcp — Workplace Gender Equality Agency
aus-identity — Postcode / state / ABN normalisation helper used by all sisters
The portfolio is designed to compose: an agent can ask for "unemployment + cash rate + median income + climate" in postcode 2000 and one shot fans out across multiple MCPs.
Roadmap (next iterations)
v0.2:
GST_MONTHLYtransposed time series; multi-yearCORP_TRANSPARENCY;ATO_OCCUPATION(salary by occupation code)v0.3: hosted version with x402 per-call paywall; programmatic SEO pages
v0.4: listing on MCPay + Apify; paid tier for high-volume agent users
CHANGELOG tracks every release.
Development
git clone https://github.com/Bigred97/ato-mcp.git
cd ato-mcp
uv venv
uv pip install -e ".[dev]"
pytest # 53 unit tests, ~7s
pytest -m live # 3 integration tests against data.gov.au, ~3sIssues, ideas, and contributions welcome: github.com/Bigred97/ato-mcp/issues.
Available Tools
7 toolsdescribe_datasetA
Describe a dataset's filterable dimensions, returnable measures, units, and source.
Use this before calling get_data on a new dataset — it tells you the valid filter keys ('state', 'postcode', 'industry'), the valid filter values ('nsw', 'vic'), the measure aliases ('median_taxable_income'), and the canonical source URL.
Returns: DatasetDetail with id, name, description, period_coverage, list of dimensions, list of measures (each with key, source_column, unit, description), and source_url + download_url.
Inputs: dataset_id (required). Returns: describe_dataset shape.
get_dataA
Query a curated ATO/ACNC dataset and return observations.
Examples: # Median taxable income in postcode 2000 (Sydney CBD), 2022-23 resp = await get_data( "IND_POSTCODE_MEDIAN", filters={"state": "nsw", "postcode": "2000"}, measures="median_taxable_income_2022_23", )
# All registered charities in NSW with size = "large"
resp = await get_data(
"ACNC_REGISTER",
filters={"state": "NSW", "charity_size": "Large"},
measures=["total_gross_income", "total_employees"],
)
# 500 ACNC charity financial records (huge dataset — cap to fit context)
resp = await get_data(
"ACNC_AIS_FINANCIALS",
filters={"state": "NSW"},
limit=500,
)
# 2023-24 corporate tax payable for entities with total income > $1B
resp = await get_data("CORP_TRANSPARENCY", filters={"income_year": "2023-24"})Returns:
DataResponse with records (or csv), unit, period bounds, row_count,
source URL, and CC-BY attribution. truncated_at is set when the
underlying slice was larger than limit.
Inputs: dataset_id (required), limit, format, filters, +3 more. Returns: get_data / latest shape — uniform across all curated datasets. `records` carrie…
latestA
Return the most recent observation(s) per measure for a dataset.
For transposed time-series tables (GST_MONTHLY etc.) this trims to the
most-recent period. For wide register-shaped tables (ACNC_REGISTER,
IND_POSTCODE etc.) it returns the same shape as get_data, capped at
limit rows. Truncated responses set DataResponse.truncated_at.
Examples: # Latest monthly net GST nationally resp = await latest("GST_MONTHLY", measures="net_gst")
# 50 charities (default cap) — narrow with filters to get specific ones
resp = await latest("ACNC_REGISTER", filters={"state": "nsw", "charity_size": "Large"})Inputs: dataset_id (required), limit, filters, measures. Returns: get_data / latest shape — uniform across all curated datasets. `records` carrie…
list_curatedA
List every curated dataset ID in this version of ato-mcp.
These are the datasets where get_data accepts plain-English filter keys and returns aliased, well-typed measure columns. Each ID is documented via describe_dataset.
Returns: Sorted list of dataset IDs.
Inputs: no named parameters. Returns: result
search_datasetsA
Fuzzy-search the curated ATO/ACNC dataset catalog.
All datasets ship hand-curated in v0.1: personal tax by postcode, company tax by industry, corporate tax transparency, GST collections, super contributions by age, the ACNC charity register, and more.
Examples: # Find the dataset that gives tax stats by postcode results = await search_datasets("postcode tax") # → [{id: 'IND_POSTCODE', name: 'Individuals by Postcode', ...}]
# Discover what's available on charities
results = await search_datasets("charity")Returns: List of DatasetSummary (id, name, description, update_frequency, is_curated), ranked by relevance.
Inputs: query (required), limit. Returns: result
statsA
Aggregate statistics (count, sum, mean, median, min, max, stddev) for one measure across all rows matching filters. Optionally grouped.
Without group_by: returns one stats payload over all matching rows.
With group_by: returns per-group stats — much more powerful for
"distribution X by Y" queries that would otherwise require N filtered
calls.
Examples: # Single aggregate over NSW postcodes stats("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23", filters={"state": "nsw"}) # → {statistics: {count: 587, mean: 55017, median: 53484, ...}}
# Stats grouped by state — one call instead of 8
stats("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
group_by="state")
# → {by: "state", groups: [
# {key: "ACT", statistics: {...}},
# {key: "NSW", statistics: {...}},
# ...
# ]}
# Tax payable per income year across the corporate sector
stats("CORP_TRANSPARENCY", "tax_payable", group_by="income_year")Returns:
Without group_by: dict with statistics field.
With group_by: dict with by and groups fields; each group
carries key, statistics, plus the same envelope
metadata (dataset_id, unit, attribution, etc.).
Inputs: measure (required), dataset_id (required), filters, group_by. Returns: object
top_nA
Return the N rows with the largest (or smallest) value of a measure.
This is the most common agent workflow: "show me the top 10 X by Y". Without this tool, an agent would call get_data, receive the full table, and then sort/slice locally — wasting tokens and turns. top_n does the rank server-side and returns only the requested rows.
Examples: # Top 10 corporate taxpayers in 2023-24 top_n("CORP_TRANSPARENCY", "tax_payable", n=10)
# 20 NSW postcodes with the highest median income (2022-23)
top_n("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
filters={"state": "nsw"}, n=20)
# 5 lowest-income postcodes in QLD
top_n("IND_POSTCODE_MEDIAN", "median_taxable_income_2022_23",
filters={"state": "qld"}, n=5, direction="bottom")Returns:
DataResponse with at most n records, sorted by measure value
in the requested direction. Other fields (period, unit, attribution)
match a regular get_data call.
Inputs: measure (required), dataset_id (required), n, filters, +1 more. Returns: get_data / latest shape — uniform across all curated datasets. `records` carrie…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clear role: discovery, metadata, raw querying, latest observations, top-N ranking, and aggregation. The only minor overlap is between get_data and latest for register-shaped datasets, but the descriptions and examples sufficiently distinguish them.
Most tools follow a verb_noun pattern (list_curated, search_datasets, describe_dataset, get_data). The exceptions are latest, top_n, and stats, which are terse noun/adjective-style names, creating a slight inconsistency but not confusion.
Seven tools is well-scoped for a data query server: discovery, schema description, retrieval, and common analytical shortcuts are each represented. No redundant tools and no sign of unnecessary bulk.
The tool surface covers the full workflow: finding datasets, understanding their schemas, pulling data, getting recent values, ranking, and aggregating. There are no obvious dead ends for common analytical queries on curated ATO/ACNC data.
Maintenance
Related MCP Connectors
Search, filter, count and sum Australian government open data, with every version kept.
Find open Australian and NZ tenders and grants, match them to a company, and see who holds the work.
Cited Australian tax answers from 34,500+ ATO documents, legislation and public rulings.
Search Australian businesses and look up ABN and GST records from the Australian Business Register.
Related MCP Servers
- AlicenseAqualityAmaintenanceOne-call Australian prudential data plumbing via APRA — cited responses for banking, superannuation and insurance context, not a data broker.6161 PyPIMIT
- AlicenseAqualityFmaintenanceCited Australian stats via the ausdata.io gateway — stable AU.* series IDs, source_url + retrieved_at on every response. Free tier. Not a data broker; upgrade for Embed / signed / webhooks.2832 npm2MIT
- AlicenseAqualityCmaintenanceProvides real tax calculations for US, Canada, Australia, and UK income, property, and dividend taxes using up-to-date local data with no API keys required.757 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server that connects AI agents to 34,500+ Australian Taxation Office documents, providing cited answers, tax deduction discovery, depreciation scheduling, BAS checklists, and audit risk assessment through 13 specialized tools.109 npm19AGPL 3.0