Skip to main content
Glama

ato-mcp

mcp-name: io.ausdata/ato-mcp

PyPI Python License Tests CodeQL Glama MCP server quality

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

Related 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

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.


Curated datasets (14)

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.


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)

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_MONTHLY transposed time series; multi-year CORP_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, ~3s

Issues, ideas, and contributions welcome: github.com/Bigred97/ato-mcp/issues.

Available Tools

7 tools
describe_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

    A4.3/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Cited 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.
      28
      32 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      7
      57 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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 npm
      19
      AGPL 3.0