readrba-mcp

readrba-mcp is a local Model Context Protocol (MCP) server for public Reserve Bank of Australia data. It exposes six read-only tools backed by the R package readrba.

This repository is a prototype. It does not provide an HTTP service or a guaranteed response cache.

How it works

The TypeScript server handles MCP schemas, validation, timeouts, and stdio. Each tool call starts one R process. The R worker loads the required packages, runs one readrba request, and returns one JSON result.

R and package diagnostics go to stderr. Stdout is reserved for MCP JSON-RPC.

Requirements

• Node.js 20 or later.
• R with Rscript available.
• R packages: pacman, readrba, jsonlite, dplyr, tibble, and purrr.

Install the R packages once:

install.packages(
  c("pacman", "readrba", "jsonlite", "dplyr", "tibble", "purrr")
)

Then install and build the server:

git clone https://github.com/dominic-behrens/readrba-mcp.git
cd readrba-mcp
npm install
npm run build

Run the server directly:

npm start

It will wait for an MCP client on stdin.

Tools

Every tool accepts offset, which defaults to 0, and max_rows, which defaults to 1000. offset must be a non-negative integer. max_rows must be a positive integer and has no configured ceiling.

Tool	Main arguments
rba_search_series	Optional query
rba_search_tables	Optional query; refresh = false
rba_get_series	Required series_ids; vintage = current; optional inclusive start_date, end_date; update_urls = false
rba_get_table	Required table_numbers; the same vintage, date, and URL options
rba_get_forecasts	scope = latest; refresh = true; remove_old = true; optional series, forecast_start_date, forecast_end_date, observation_start_date, and observation_end_date
rba_get_cash_rate	type = target; optional inclusive start_date and end_date

vintage accepts current, historical, or both. type accepts target, interbank, or both.

For a both table or series request, overlapping observations are retained. The response includes rba_vintage; the server does not deduplicate the two sources.

Results and errors

Filters and deterministic sorting are applied before pagination. Successful tools return the same object as JSON text and as MCP structured content:

{
  "data": [],
  "total_rows": 0,
  "returned_rows": 0,
  "offset": 0,
  "max_rows": 1000,
  "has_more": false,
  "truncated": false
}

has_more reports whether later rows remain. truncated is true when the response does not contain every matching row, including when offset skips earlier rows.

Dates are serialized as YYYY-MM-DD. Missing R values are JSON null. Validation, R, download, timeout, worker, and unknown-series failures are returned as MCP tool errors with isError: true.

Configuration

Environment variable	Default	Purpose
RSCRIPT_PATH	Rscript	Rscript executable
READRBA_DOWNLOAD_PATH	~/.readrba-mcp/downloads	Directory for RBA spreadsheet downloads and R temporary files
READRBA_TIMEOUT_MS	180000	Positive worker timeout in milliseconds

On some corporate Windows networks, readrba may also require R_READRBA_DL_METHOD=wininet.

readrba can overwrite downloaded spreadsheets in READRBA_DOWNLOAD_PATH. The directory is outside this repository by default, so raw downloads are not committed. These files are package working files, not a stable or complete response cache.

Client setup

Build the server first. Replace each placeholder path below with a path that is valid in the client’s operating environment.

Windows

Use native Windows paths when the client runs on Windows:

{
  "mcpServers": {
    "readrba": {
      "command": "node",
      "args": ["C:\\path\\to\\readrba-mcp\\dist\\index.js"],
      "env": {
        "RSCRIPT_PATH": "C:\\Program Files\\R\\R-4.5.3\\bin\\x64\\Rscript.exe"
      }
    }
  }
}

WSL

Use WSL paths when Node runs in WSL. A Windows R installation can be called through its mounted path:

{
  "mcpServers": {
    "readrba": {
      "command": "node",
      "args": ["/path/to/readrba-mcp/dist/index.js"],
      "env": {
        "RSCRIPT_PATH": "/mnt/c/Program Files/R/R-4.5.3/bin/x64/Rscript.exe"
      }
    }
  }
}

Alternatively, install R inside WSL and omit RSCRIPT_PATH if Rscript is on PATH.

Codex

The current Codex CLI accepts a stdio command after -- and environment variables through repeated --env options:

codex mcp add \
  --env RSCRIPT_PATH=/path/to/Rscript \
  readrba -- node /path/to/readrba-mcp/dist/index.js

See the Codex MCP documentation for configuration scope and other options.

Claude Code

Claude Code uses the same command separator:

claude mcp add \
  --env RSCRIPT_PATH=/path/to/Rscript \
  readrba -- node /path/to/readrba-mcp/dist/index.js

Use --scope user or --scope project if required. See Claude Code MCP setup.

Other stdio clients

Configure:

• command: node
• arguments: /path/to/readrba-mcp/dist/index.js
• environment: set RSCRIPT_PATH if Rscript is not on PATH

The process must receive MCP JSON-RPC on stdin and have exclusive use of stdout.

Development and tests

npm test

This builds strict TypeScript and exercises the built server through the MCP v2 client over stdio. It checks all six schemas, validation, pagination, structured content, ISO dates, JSON nulls, clean errors, and stderr isolation.

Run the offline R catalogue checks:

TEST_RSCRIPT_PATH=/path/to/Rscript npm run test:r:offline

Run live RBA smoke tests:

READRBA_LIVE_TEST=1 \
TEST_RSCRIPT_PATH=/path/to/Rscript \
npm run test:live

The live tests cover CPI series GCPIAG, both vintages of table A1, latest forecasts, and target, interbank, and combined cash rates.

Attribution

The server architecture is adapted from jonobri/readabs-mcp. RBA data access is provided by MattCowgill/readrba.

This project is not affiliated with the Reserve Bank of Australia.

Licence

MIT. See LICENSE.