# readrba-mcp

`readrba-mcp` is a local Matt Cowgill Protocol (MCP) server for public
Reserve Bank of Australia data. It exposes six read-only tools backed by the
R package [`readrba`](https://mattcowgill.github.io/readrba/).

This repository is a prototype and has not been tested extensively!!! Use with Caution!!!

## 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:

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

Then install and build the server:

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

Run the server directly:

```bash
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:

```json
{
  "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:

```json
{
  "mcpServers": {
    "readrba": {
      "command": "node",
      "args": ["C:\\path\\to\\readrba-mcp\\dist\\index.js"],
      "env": {
        "RSCRIPT_PATH": "\\path\\to\\rscript"
      }
    }
  }
}
```

### WSL

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

```json
{
  "mcpServers": {
    "readrba": {
      "command": "node",
      "args": ["/path/to/readrba-mcp/dist/index.js"],
      "env": {
        "RSCRIPT_PATH": "\\path\\to\\rscript"
      }
    }
  }
}
```

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:

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

See the
[Codex MCP documentation](https://developers.openai.com/codex/concepts/customization#mcp)
for configuration scope and other options.

### Claude Code

Claude Code uses the same command separator:

```bash
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](https://docs.anthropic.com/en/docs/claude-code/mcp).

### 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

```bash
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:

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

Run live RBA smoke tests:

```bash
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`](https://github.com/jonobri/readabs-mcp). RBA data
access is provided by
[`MattCowgill/readrba`](https://github.com/MattCowgill/readrba).

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

## Licence

MIT. See [LICENSE](LICENSE).