upbank-mcp

A Model Context Protocol server that exposes the Up Banking API to LLM clients, built with FastMCP and packaged for Docker.

It provides 19 tools and 2 resources covering the complete public surface of the Up API — accounts, transactions, categories, tags, attachments and webhooks — with responses reshaped for token efficiency, cursor pagination preserved end to end, and automatic retry on rate limits.

Contents

• Requirements

• Quick start

• Configuration

• Running the server

• Connecting an MCP client

• Tool reference

• Resources

• Response conventions

• Error handling and rate limits

• Project layout

• Development

• Security

• Troubleshooting

Related MCP server: Up Bank MCP Server

Requirements

The Up API is available to Up customers in Australia. A token grants access to the issuing customer's own data only.

Quick start

git clone git@github.com:uiux-me/upbank-mcp.git
cd upbank-mcp
cp .env.example .env          # paste your token into UP_API_TOKEN
docker compose up --build

The server listens on http://127.0.0.1:8000/mcp. Verify it:

docker compose exec upbank-mcp python -c "
import asyncio, upbank_mcp
from fastmcp import Client
async def main():
    async with Client(upbank_mcp.mcp) as c:
        print((await c.call_tool('ping')).data)
asyncio.run(main())"

A healthy response is your customer id and a status emoji:

{'ok': True, 'id': 'eb59f467-…', 'status_emoji': '⚡️'}

Configuration

All configuration is by environment variable. Compose reads .env from the project directory automatically.

Running the server

HTTP, via Compose

Best for a long-running server shared by several clients on your machine.

docker compose up --build          # foreground
docker compose up -d --build       # detached
docker compose logs -f             # follow logs
docker compose down                # stop and remove

The port is published on 127.0.0.1 only. See Security.

stdio, via Docker

Best for MCP clients that spawn the server as a subprocess. Build the image once:

docker build -t upbank-mcp:latest .

The image defaults to MCP_TRANSPORT=stdio, so no transport override is needed.

Without Docker

pip install -e .
export UP_API_TOKEN=up:yeah:...
upbank-mcp

Set MCP_TRANSPORT=http to serve over HTTP instead of stdio.

Connecting an MCP client

Claude Code

claude mcp add upbank \
  -e UP_API_TOKEN=up:yeah:... \
  -- docker run -i --rm -e UP_API_TOKEN upbank-mcp:latest

Claude Desktop, or any client using mcpServers config

{
  "mcpServers": {
    "upbank": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "UP_API_TOKEN", "upbank-mcp:latest"],
      "env": { "UP_API_TOKEN": "up:yeah:..." }
    }
  }
}

-i is required — the server communicates over stdin/stdout. --rm cleans up the container when the client disconnects.

Over HTTP

Point the client at http://127.0.0.1:8000/mcp while the Compose stack is running.

Tool reference

Required parameters are bold. Every list tool accepts cursor; see Pagination.

Utility

Accounts

Transactions

since and until bound createdAt inclusively. category accepts a parent id, which matches all of its children.

Categories

Categories are fixed by Up and cannot be created. Ids are slugs such as restaurants-and-cafes. Only transactions with is_categorizable: true can be changed, and only leaf categories are accepted — passing a parent such as good-life returns HTTP 403.

Tags

A transaction holds at most 6 tags. Tags with no remaining transactions disappear from list_tags.

Attachments

file_url is a signed URL that expires at file_url_expires_at. Fetch it promptly or re-request the attachment.

Webhooks

secret_key is returned only at creation and never again. Store it to verify the X-Up-Authenticity-Signature header (SHA-256 HMAC) on incoming deliveries.

Resources

Both are read on demand and reflect state at read time.

Response conventions

Shape

Up returns JSON:API, which nests every field under attributes/relationships and repeats self-links on each resource. This server flattens each resource into a compact dict and omits optional fields when absent, which materially reduces token cost without losing information a caller needs.

{
  "id": "45b83097-c97d-40da-9790-254056f03d40",
  "status": "SETTLED",
  "description": "Google One",
  "amount": { "value": "-2.49", "currency": "AUD", "base_units": -249 },
  "created_at": "2026-08-20T06:53:17+10:00",
  "settled_at": "2026-08-20T06:53:17+10:00",
  "account_id": "90c0fffc-bed6-4214-9450-6a76cd39957b",
  "category_id": "games-and-software",
  "parent_category_id": "good-life",
  "tags": [],
  "is_categorizable": true
}

Fields such as foreign_amount, hold_info, round_up, cashback, card_purchase_method, note and message appear only when the transaction has them.

Money

Every amount is an object:

{ "value": "-2.49", "currency": "AUD", "base_units": -249 }

value is a decimal string, base_units is the integer minor unit (cents for AUD). Debits are negative. Prefer base_units for arithmetic to avoid float error.

Pagination

List tools return:

{ "items": [ ... ], "next_cursor": "https://api.up.com.au/...", "prev_cursor": null }

To page, pass a returned cursor back as the cursor argument of the same tool. Cursors are Up's own opaque URLs and already encode the filters and page size, so all other arguments are ignored when cursor is set. A null cursor means no further page in that direction.

Cursors are validated against the configured API host before being followed, so a cursor cannot redirect the client to another server.

Dates

since and until accept either YYYY-MM-DD or a full RFC-3339 timestamp. Bare dates and naive datetimes are anchored to Australia/Sydney, matching how Up presents times in the app; the correct offset is applied for the date in question, so daylight saving is handled. Unparseable input is rejected before the request is made, rather than surfacing as an opaque HTTP 400.

Error handling and rate limits

• API errors are raised as ToolError with the HTTP status and Up's own error title and detail, for example: HTTP 403 — Forbidden: Top-level categories cannot be set directly on transactions.

• 429 and 5xx responses are retried up to 3 times with exponential backoff, honouring the Retry-After header when present.

• Network failures are retried on the same schedule before surfacing.

• 4xx responses other than 429 are not retried — they indicate a bad request.

Project layout

src/upbank_mcp/
├── client.py     Async HTTP client: auth, retry/backoff, date normalisation,
│                 cursor host validation
├── shapes.py     JSON:API → flat dict transforms, one per resource type
├── server.py     FastMCP instance, tool and resource definitions, entrypoint
├── __init__.py   Exports `mcp` and `main`
└── __main__.py   Enables `python -m upbank_mcp`

The separation is deliberate: client.py knows about HTTP and nothing about MCP, shapes.py is pure data transformation, and server.py holds the tool contracts. Each is independently testable.

Development

pip install -e .
export UP_API_TOKEN=up:yeah:...
upbank-mcp                              # stdio
MCP_TRANSPORT=http upbank-mcp           # http on :8000

Drive the server in-process with the FastMCP client:

import asyncio
from fastmcp import Client
import upbank_mcp

async def main():
    async with Client(upbank_mcp.mcp) as client:
        print(await client.list_tools())
        result = await client.call_tool("list_accounts", {"account_type": "TRANSACTIONAL"})
        print(result.data)

asyncio.run(main())

Rebuild the image after changes:

docker compose up -d --build

Security

The token is powerful. Up personal access tokens cannot move money — the API has no payment or transfer endpoint — but they can read your complete transaction history and mutate categories, tags and webhooks. Treat one like a password.

• The HTTP transport has no authentication of its own. Anything that can reach the port can read your banking data. Compose therefore publishes to 127.0.0.1 only. Do not bind it to 0.0.0.0 or expose it through a tunnel or reverse proxy without putting authentication in front of it.

• The token is never baked into an image. .env is listed in .dockerignore, and the token is supplied at runtime. It does not appear in any image layer, so the image is safe to push to a registry.

• .env is gitignored, and .env.example carries a placeholder only.

• The container runs as a non-root user (uid 10001).

• Rotate immediately at https://api.up.com.au/getting_started if a token is ever exposed. Tokens do not expire on their own.

Troubleshooting

Reference

• Up API documentation

• Up API OpenAPI spec and Postman collection

• FastMCP documentation

• Model Context Protocol specification