{
  "markdown": "# abs-mcp\n\nmcp-name: io.ausdata/abs-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/abs-mcp.svg)](https://pypi.org/project/abs-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/abs-mcp.svg)](https://pypi.org/project/abs-mcp/)\n[![License](https://img.shields.io/pypi/l/abs-mcp.svg)](https://github.com/Bigred97/abs-mcp/blob/main/LICENSE)\n[![Tests](https://github.com/Bigred97/abs-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Bigred97/abs-mcp/actions/workflows/test.yml)\n[![CodeQL](https://github.com/Bigred97/abs-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Bigred97/abs-mcp/actions/workflows/codeql.yml)\n[![Glama MCP server quality](https://glama.ai/mcp/servers/Bigred97/abs-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Bigred97/abs-mcp)\n\n**Ask Claude about the Australian economy and get real, current numbers** — not \"I don't have access to that data.\" This MCP server gives Claude (and other MCP clients like Cursor) live access to the [ABS Data API](https://data.api.abs.gov.au/), with curated mappings for the 10 most-asked Australian economic indicators.\n\n> **Hosted access?** For cross-source queries, webhooks, an always-on REST API, and a uniform response envelope across all 9 sources, see **[ausdata.io](https://ausdata.io)** — free tier available (500 calls/mo, no card).\n\n![abs-mcp answering \"What's the unemployment rate in NSW?\" in Claude Desktop](docs/demo.png)\n\nBehind the scenes it wraps SDMX 2.1, but you never see SDMX codes — just plain-English filters like `region: \"nsw\"` and `measure: \"unemployment_rate\"`. Five tools, ten curated dataflows (Labour Force, CPI, Wage Price Index, Job Vacancies, Average Weekly Earnings, GDP / National Accounts, quarterly + annual Estimated Resident Population, Building Approvals, Lending Indicators), and 1,200+ other ABS dataflows accessible via raw codes.\n\nCompanion to [rba-mcp](https://github.com/Bigred97/rba-mcp) (Reserve Bank of Australia — cash rate, FX, lending rates), [ato-mcp](https://github.com/Bigred97/ato-mcp) (Australian Taxation Office — postcode-level personal tax, company tax by industry, corporate tax transparency, ACNC charity register), and [au-weather-mcp](https://github.com/Bigred97/au-weather-mcp) (Australian weather — 21 curated locations + postcode/place-name lookup, current observations, 16-day forecasts, 80yr historical archive). Install all four for the full AU macro / regulator / tax / climate stack.\n\n## What you can ask\n\nOnce installed, your LLM can answer questions like:\n\n| Question | Real response (verified) |\n|---|---|\n| What's the unemployment rate in NSW? | **4.27%** (Mar 2026) |\n| AU annual CPI inflation? | **4.60%** (Mar 2026) |\n| AU annual wage growth? | **3.40%** (Q4 2025) |\n| Average weekly earnings in Australia? | **$1,562** (Sep–Oct 2025) |\n| AU GDP quarterly growth? | **0.80%** (Q4 2025) |\n| AU GDP per capita? | **$24,900/qtr** (Q4 2025) |\n| Job vacancies in NSW? | **101,200** (Q1 2026) |\n| Dwelling approvals in NSW? | **4,400/month** (Mar 2026) |\n| New NSW housing loan commitments? | **$19.7B** (Q4 2025) |\n| Quarterly population of Australia? | **27.7M** (Q3 2025) |\n\nEvery answer comes with the period, units, and a link back to the ABS source page. Comparisons and time-series queries work just as well — see [Worked examples](#worked-examples) below.\n\n## Install\n\n```bash\n# After publish:\nuvx --upgrade abs-mcp\n\n# Local dev install:\nuv pip install -e .\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"abs\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--upgrade\", \"abs-mcp\"]\n    }\n  }\n}\n```\n\n> **Why `--upgrade`?** `uvx abs-mcp` (without the flag) uses whatever wheel is cached and never adopts new PyPI releases on its own — Claude Desktop's MCP child process keeps running the same wheel until you fully quit the app and refresh the cache by hand. `--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` (added in 0.2.10).\n\nFor a local checkout (before PyPI publish):\n\n```json\n{\n  \"mcpServers\": {\n    \"abs\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/abs-mcp\", \"abs-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The `abs` server appears in the tools panel with five tools.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (or workspace `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"abs\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--upgrade\", \"abs-mcp\"]\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `search_datasets(query, limit=10)` | Fuzzy-search ABS dataflow names. Returns the top matches. |\n| `describe_dataset(dataset_id)` | Plain-English description of a dataflow's dimensions and values. |\n| `get_data(dataset_id, filters, start_period, end_period, format)` | Query a dataflow with filters. Returns clean records (default), grouped series, or CSV. |\n| `latest(dataset_id, filters)` | Just the most recent observation(s) — wraps `get_data` with `lastNObservations=1`. |\n| `top_n(dataset_id, measure, n=10, filters=None, direction=\"top\")` | Rank rows of a curated dataflow by a measure (e.g. `unemployment_rate`) at the most-recent period and return the top (or bottom) N. |\n| `list_curated()` | The ten dataflow IDs that have hand-curated plain-English support. |\n\n## Curated dataflows\n\nFor these curated dataflows, `filters` accepts plain-English values (e.g. `\"region\": \"nsw\"` instead of `\"REGION\": \"1\"`):\n\n- **LF** — Labour Force, monthly: employment, unemployment, participation by state/sex\n- **CPI** — Consumer Price Index, quarterly inflation (cat 6401.0 — the headline rate)\n- **CPI_MONTHLY** — Monthly CPI Indicator (cat 6484.0), full sub-category and per-city breakdown\n- **WPI** — Wage Price Index, quarterly wage growth by industry/sector/state\n- **PPI_FD** — Producer Price Index Final Demand, quarterly producer inflation\n- **JV** — Job Vacancies, quarterly labour demand by industry/sector/state\n- **AWE** — Average Weekly Earnings, half-yearly by industry/sector/state\n- **ANA_AGG** — National Accounts: GDP, GDP per capita, terms of trade, real income (Australia, quarterly)\n- **ABS_ANNUAL_ERP_ASGS2021** — Estimated Resident Population, annual by state and sub-state geography\n- **ERP_Q** — Quarterly Estimated Resident Population, by state/sex/age\n- **BUILDING_APPROVALS** — Building Approvals (cat 8731.0), monthly by state/capital region, building type (houses / townhouses / apartments / total dwellings / non-residential) and measure (number / value). The property-economist \"Building Index\" series.\n- **BA_GCCSA** — Building Approvals, monthly by state/capital region and building type (raw GCCSA dimension surface; `BUILDING_APPROVALS` is the cleaner alias)\n- **BA_LGA2024** — Building Approvals at the **council (Local Government Area) level**, monthly, ~570 councils — far more granular than BA_GCCSA's 8-capital geography. Pass `region=` an LGA code (e.g. `\"10050\"` Albury, `\"22750\"` Greater Geelong, `\"31000\"` Brisbane) for council-by-council approvals; defaults to Brisbane. Council-level only — for state / national totals use `BUILDING_APPROVALS`. Resolves to ABS's current `BA_LGA2025` SDMX dataflow so the series stays live.\n- **BUILDING_ACTIVITY** — Building Activity (cat 8752.0), quarterly dwelling units **completed** / commenced / under construction plus value of work, by state and building type. The trailing-reality counterpart to `BUILDING_APPROVALS` — pair the two for approvals-vs-completions, and add `NOM` for the supply-vs-migration story.\n- **NOM** — Net Overseas Migration (cat 3412.0), financial-year arrivals/departures/**net** by state and age. The dominant rents-vs-migration series; publishes the headline net figure to the latest FY.\n- **ABS_NOM_VISA_CY** — NOM by visa subclass (calendar year, student / skilled / working holiday / permanent streams)\n- **LEND_HOUSING** — Lending Indicators, quarterly new housing loan commitments by purpose, lender, and state\n- **HSI_M** — Monthly Household Spending Indicator (ABS-blessed retail-trade replacement), COICOP category × discretionary × state\n- **RT** — Retail Trade (43-year historical series, ceased Jul 2025)\n- **C21_G01_POA / C21_G02_POA / C21_G02_SA2** — Census 2021 selected characteristics and medians by postcode / SA2\n\nAny other ABS dataflow still works — pass raw SDMX dimension IDs and codes.\n\n## Worked examples\n\n> **Cross-source compatibility.** All location filters accept canonical state\n> codes (`\"NSW\"`), full names (`\"New South Wales\"`), case-insensitive\n> variants (`\"nsw\"`), ISO 3166-2 (`\"AU-NSW\"`), and 4-digit postcodes\n> (`\"2000\"` → NSW). Powered by [`aus-identity`](https://pypi.org/project/aus-identity/) —\n> the same input format works across abs-mcp, ato-mcp, apra-mcp, aihw-mcp,\n> and asic-mcp.\n\n**\"What's the current unemployment rate in NSW?\"**\n\nClaude calls:\n```\nlatest(dataset_id=\"LF\", filters={\"region\": \"nsw\", \"measure\": \"unemployment_rate\"})\n```\n\nReturns:\n```json\n{\n  \"dataset_id\": \"LF\",\n  \"dataset_name\": \"Labour Force\",\n  \"query\": {\"region\": \"nsw\", \"measure\": \"unemployment_rate\"},\n  \"period\": {\"start\": \"2026-03\", \"end\": \"2026-03\"},\n  \"unit\": \"Percent\",\n  \"records\": [\n    {\n      \"period\": \"2026-03\",\n      \"value\": 4.27,\n      \"dimensions\": {\"measure\": \"Unemployment rate\", \"region\": \"New South Wales\", \"sex\": \"Persons\"},\n      \"unit\": \"Percent\"\n    }\n  ],\n  \"source\": \"Australian Bureau of Statistics\",\n  \"retrieved_at\": \"2026-05-11T03:14:22Z\",\n  \"abs_url\": \"https://www.abs.gov.au/statistics/labour/employment-and-unemployment/labour-force-australia\"\n}\n```\n\n**\"Show me NSW housing approvals over the last two years\"**\n\n```\nget_data(dataset_id=\"BA_GCCSA\", filters={\"region\": \"nsw\", \"measure\": \"dwelling_units\"}, start_period=\"2024\")\n```\n\n**\"Compare monthly CPI inflation in Sydney vs Melbourne\"**\n\n```\nget_data(dataset_id=\"CPI_MONTHLY\", filters={\"region\": [\"sydney\", \"melbourne\"], \"measure\": \"change_year\"}, start_period=\"2023\")\n```\n\n(`CPI` itself publishes only the national weighted average at quarterly cadence; the monthly indicator carries per-city series.)\n\n## Period formats\n\nABS uses different period formats per dataflow. Pass `start_period` / `end_period` in the matching format:\n\n| Dataflows | Frequency | Format | Example |\n|---|---|---|---|\n| LF, BA_GCCSA, BUILDING_APPROVALS | Monthly | `YYYY-MM` | `\"2026-03\"` |\n| BUILDING_ACTIVITY | Quarterly | `YYYY-Qn` | `\"2025-Q4\"` |\n| CPI, WPI, PPI_FD, JV, ANA_AGG, LEND_HOUSING, ERP_Q | Quarterly | `YYYY-Q*` | `\"2025-Q4\"` |\n| CPI_MONTHLY, HSI_M | Monthly | `YYYY-MM` | `\"2025-12\"` |\n| AWE | Half-yearly | `YYYY-S*` | `\"2025-S2\"` |\n| NOM (financial year), ABS_ANNUAL_ERP_ASGS2021 | Annual | `YYYY` | `\"2025\"` |\n\n## Verifying your install\n\nThe running MCP server reports its version on every `DataResponse`:\n\n```json\n{ ..., \"server_version\": \"0.2.11\", ... }\n```\n\nIf you see a value below the [latest on PyPI](https://pypi.org/project/abs-mcp/), your `uvx` cache is stale. Either switch to `[\"--upgrade\", \"abs-mcp\"]` in your config (recommended), or refresh manually:\n\n```bash\nuvx --refresh abs-mcp --help\n# Then fully quit and relaunch Claude Desktop (Cmd+Q — window-close is not enough).\n```\n\nClaude Desktop's MCP child processes are long-lived; refreshing the wheel cache does **not** restart an already-running server. Cold app launch is required.\n\n## Development\n\n```bash\ngit clone https://github.com/Bigred97/abs-mcp.git\ncd abs-mcp\nuv sync --extra dev\nuv pip install -e .\n\n# Unit tests (no network)\nuv run pytest\n\n# Live integration tests (hits real ABS API)\nuv run pytest -m live\n```\n\nThe SQLite cache lives at `~/.abs-mcp/cache.db`. Catalogue refreshes every 24h, codelists every 7 days, data responses every hour, latest 15 minutes. Delete the file to force a refresh.\n\n## How it works\n\nWhen you ask Claude an ABS question, it picks the right tool, fills in the curated filters, and calls the live ABS API. You see the reasoning + tool call inline:\n\n![Claude reasoning + tool call panel](docs/tool-call.png)\n\nClaude does the picking; this server does the SDMX translation, unit attribution, and clean response shaping. You don't have to know what `M13.3.1599.20.1.M` means — and neither does Claude.\n\n## How it differs from existing ABS MCP servers\n\nThe one existing community option (`seansoreilly/abs`) exposes a single `query_dataset` tool that passes raw SDMX through. This package offers semantic tools and curated mappings for the highest-value dataflows so an LLM can answer real questions without you needing to know what `M13.3.1599.20.1.M` means.\n\n## Sister MCPs (Australian Public Data portfolio)\n\n> **Want all 9 sources behind one REST API?** The hosted gateway at **[ausdata.io](https://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).\n\n- **abs-mcp** — this one. Australian Bureau of Statistics (CPI, unemployment, ERP, building approvals)\n- [rba-mcp](https://pypi.org/project/rba-mcp/) — Reserve Bank of Australia (cash rate, lending stats, exchange rates)\n- [ato-mcp](https://pypi.org/project/ato-mcp/) — Australian Taxation Office (tax stats, ACNC charities)\n- [apra-mcp](https://pypi.org/project/apra-mcp/) — Australian Prudential Regulation Authority (banking, insurance, super)\n- [aihw-mcp](https://pypi.org/project/aihw-mcp/) — Australian Institute of Health and Welfare\n- [asic-mcp](https://pypi.org/project/asic-mcp/) — Australian Securities and Investments Commission (company registers)\n- [aemo-mcp](https://pypi.org/project/aemo-mcp/) — Australian Energy Market Operator (NEM dispatch, spot prices, generation)\n- [au-weather-mcp](https://pypi.org/project/au-weather-mcp/) — Open-Meteo (Bureau of Meteorology aggregator)\n- [wgea-mcp](https://pypi.org/project/wgea-mcp/) — Workplace Gender Equality Agency\n- [aus-identity](https://pypi.org/project/aus-identity/) — Postcode / state / ABN normalisation helper used by all sisters\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## License\n\nMIT — Harry Vass, 2026.\n",
  "bytes": 14125,
  "sha": "e70c2a17854d9705f78a9d0658904abae20f7bfd06ffffa1b366283381d67f97",
  "repo_slug": "bigred97/abs-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_ausdata_abs_mcp_cd90feb8/readme"
}