ato-mcp
Advanced tools
MCP server for Australian Taxation Office statistics. Plain-English access to personal tax by postcode, company tax by industry, corporate tax transparency, GST collections, super contributions, and the ACNC charity register.
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.
# Run on demand via uvx (recommended)
uvx --upgrade ato-mcp
# Or install permanently
pip install ato-mcp
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 mcp add ato --command uvx --args -- --upgrade ato-mcp
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.
Seven tools, all plain-English in, structured out:
| Tool | Purpose |
|---|---|
search_datasets | Fuzzy-search the curated catalog by keyword |
describe_dataset | List a dataset's filterable dimensions and returnable measures |
get_data | Query with filters, measures, period range, output format |
latest | Last observation per measure (shortcut) |
top_n | Rank rows by a measure, return top (or bottom) N |
stats | Aggregate stats (count, sum, mean, median, min, max, stddev) over a measure — optional group_by partitions before aggregating |
list_curated | 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.
| ID | What it is | Period | Coverage |
|---|---|---|---|
IND_POSTCODE | Personal tax stats by taxable status × state × SA4 × postcode (~5,200 postcodes) | 2022-23 | 80+ measures |
IND_POSTCODE_MEDIAN | Median & average taxable income by postcode, every year | 2003-04 → 2022-23 | 21 yearly measures |
COMPANY_INDUSTRY | Company tax by ANZSIC broad + fine industry | 2022-23 | 216 industry cells |
CORP_TRANSPARENCY | Entity-level tax disclosure for $100M+ corporations (name, ABN, income, tax) | 2023-24 | ~4,200 entities |
SUPER_CONTRIB_AGE | Super contributions by age × sex × taxable income bracket | 2022-23 | Employer/personal/other |
ACNC_REGISTER | Live register of every Australian charity (ABN, size, jurisdiction, beneficiaries) | Current (weekly) | ~60,000 entities |
GST_MONTHLY | Monthly GST / WET / LCT collections (gross GST, input tax credits, net GST, etc.) | 2020-07 → 2024-06 | 10 metrics × 48 months |
ATO_OCCUPATION | Median/average income (taxable, salary/wage, total) by ANZSCO occupation × sex | 2022-23 | ~1,200 jobs × 7 measures |
SMSF_FUNDS | SMSF sector size — total funds, total members, total gross assets (trillion-$ sector) | 2019-20 → 2024-25 | 3 metrics × 6 years |
SBB_BENCHMARKS | Industry total-expense + COGS ratio bands by turnover bracket (~100 industries) | 2023-24 | 12 measures × 100 industries |
HELP_DEBT | HECS/HELP outstanding debt, indexation, compulsory + voluntary repayments annual | 2005-06 → 2024-25 | 8 measures × 20 years |
TAX_GAPS | 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 |
RND_INCENTIVE | R&D Tax Incentive transparency — every entity's R&D claim (name, ABN, $) | 2022-23 | ~13,000 entities |
ACNC_AIS_FINANCIALS | 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.
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.
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.
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.
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).
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.
GST_MONTHLY transposed time series; multi-year CORP_TRANSPARENCY; ATO_OCCUPATION (salary by occupation code)CHANGELOG tracks every release.
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, ~3s
Issues, ideas, and contributions welcome: github.com/Bigred97/ato-mcp/issues.
FAQs
MCP server for Australian Taxation Office statistics. Plain-English access to personal tax by postcode, company tax by industry, corporate tax transparency, GST collections, super contributions, and the ACNC charity register.
The pypi package ato-mcp receives a total of 73 weekly downloads. As such, ato-mcp popularity was classified as not popular.
We found that ato-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.