# abs-mcp

> Live MCP (Model Context Protocol) server giving Claude and other LLM agents access to Australian Bureau of Statistics data — labour force, CPI, GDP, wages, housing, population — via plain-English tools. Hides SDMX behind 10 curated dataflows; 1,200+ other ABS dataflows accessible via raw codes. Python, MIT, on PyPI.

abs-mcp is a Python package installable via `uvx abs-mcp`. When configured in an MCP client like Claude Desktop or Cursor, it exposes five tools to the LLM: `search_datasets(query, limit)` for fuzzy discovery, `describe_dataset(dataset_id)` for plain-English dimension listings, `get_data(dataset_id, filters, start_period, end_period, format)` for queries, `latest(dataset_id, filters)` for the most-recent observation, and `list_curated()` for the curated dataflow IDs.

For curated dataflows (LF, CPI, WPI, JV, AWE, ANA_AGG, ABS_ANNUAL_ERP_ASGS2021, ERP_Q, BA_GCCSA, LEND_HOUSING) the LLM passes plain-English filter values like `region: "nsw"`, `measure: "unemployment_rate"`. For non-curated dataflows the LLM passes raw SDMX codes. Every response includes the period, unit, and a link to the ABS source page; numerical values are scaled by `UNIT_MULT` so an LLM doesn't need to interpret SDMX magnitude attributes.

The server is companion to `rba-mcp` (Reserve Bank of Australia data). Together they cover the most-asked Australian economic data; users typically install both side-by-side.

## Documentation
- [README](https://github.com/Bigred97/abs-mcp/blob/main/README.md): install instructions, Claude Desktop / Cursor config, worked examples table with verified real values
- [CHANGELOG](https://github.com/Bigred97/abs-mcp/blob/main/CHANGELOG.md): full release history showing how the curated mappings, response shapes, and validation guards evolved
- [Curated YAMLs](https://github.com/Bigred97/abs-mcp/tree/main/src/abs_mcp/data/curated): one YAML per curated dataflow, defining plain-English keys → SDMX codes
- [PyPI](https://pypi.org/project/abs-mcp/): latest published version, install command

## Use cases for an LLM agent
- "What's the unemployment rate in NSW?" → `latest("LF", {"region": "nsw", "measure": "unemployment_rate"})`
- "What's the AU annual inflation rate?" → `latest("CPI", {"region": "australia", "measure": "change_year"})`
- "What's AU GDP growth this quarter?" → `latest("ANA_AGG", {"series": "gdp", "measure": "change"})`
- "Compare unemployment across NSW, VIC, QLD" → `get_data("LF", {"region": ["nsw", "vic", "qld"], "measure": "unemployment_rate"}, start_period="2020")`
- "How many dwellings were approved in NSW last month?" → `latest("BA_GCCSA", {"region": "nsw", "measure": "dwelling_units"})`
- Discovery: when the dataflow ID is unknown, call `search_datasets("housing finance")` then `describe_dataset(top_result.id)`

## Source
- [src/abs_mcp/server.py](https://github.com/Bigred97/abs-mcp/blob/main/src/abs_mcp/server.py): FastMCP entrypoint, the 5 tool definitions
- [src/abs_mcp/curated.py](https://github.com/Bigred97/abs-mcp/blob/main/src/abs_mcp/curated.py): YAML loader + plain-English filter translation
- [src/abs_mcp/shaping.py](https://github.com/Bigred97/abs-mcp/blob/main/src/abs_mcp/shaping.py): SDMX → records / series / csv response shaping
- [src/abs_mcp/client.py](https://github.com/Bigred97/abs-mcp/blob/main/src/abs_mcp/client.py): async ABS API client (httpx + sdmx1)

## Optional
- [Companion server: rba-mcp](https://github.com/Bigred97/rba-mcp): Reserve Bank of Australia data (cash rate, FX, mortgage rates) using the same plain-English pattern
- [Tests](https://github.com/Bigred97/abs-mcp/tree/main/tests): 161 tests covering every curated dataflow + URL-injection guards + search relevance
