upbank-mcp

Ein Model Context Protocol-Server, der die Up Banking API für LLM-Clients bereitstellt, gebaut mit FastMCP und für Docker verpackt.

Er bietet 19 Tools und 2 Ressourcen, die die gesamte öffentliche Oberfläche der Up API abdecken — Konten, Transaktionen, Kategorien, Tags, Anhänge und Webhooks — mit für Tokeneffizienz umgeformten Antworten, durchgängig erhaltener Cursor-Paginierung und automatischen Wiederholungsversuchen bei Rate Limits.

Inhalt

• Voraussetzungen

• Schnellstart

• Konfiguration

• Server ausführen

• MCP-Client verbinden

• Tool-Referenz

• Ressourcen

• Antwort-Konventionen

• Fehlerbehandlung und Rate Limits

• Projektstruktur

• Entwicklung

• Sicherheit

• Fehlerbehebung

Related MCP server: Up Bank MCP Server

Voraussetzungen

Die Up API ist für Up-Kunden in Australien verfügbar. Ein Token gewährt ausschließlich Zugriff auf die eigenen Daten des ausstellenden Kunden.

Schnellstart

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

Der Server lauscht auf http://127.0.0.1:8000/mcp. So überprüfen Sie ihn:

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())"

Eine fehlerfreie Antwort enthält Ihre Kunden-id und ein Status-Emoji:

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

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Compose liest .env automatisch aus dem Projektverzeichnis.

Server ausführen

HTTP, via Compose

Am besten für einen langlebigen Server, der von mehreren Clients auf Ihrem Rechner gemeinsam genutzt wird.

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

Der Port wird nur auf 127.0.0.1 veröffentlicht. Siehe Sicherheit.

stdio, via Docker

Am besten für MCP-Clients, die den Server als Unterprozess starten. Bauen Sie das Image einmal:

docker build -t upbank-mcp:latest .

Das Image verwendet standardmäßig MCP_TRANSPORT=stdio, daher ist keine Transport-Überschreibung erforderlich.

Ohne Docker

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

Setzen Sie MCP_TRANSPORT=http, um über HTTP statt stdio zu dienen.

MCP-Client verbinden

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 oder jeder Client, der die mcpServers-Konfiguration verwendet

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

-i ist erforderlich — der Server kommuniziert über stdin/stdout. --rm entfernt den Container, wenn der Client die Verbindung trennt.

Über HTTP

Richten Sie den Client auf http://127.0.0.1:8000/mcp, während der Compose-Stack läuft.

Tool-Referenz

Erforderliche Parameter sind fett. Jedes Listen-Tool akzeptiert cursor; siehe Paginierung.

Dienstprogramm

Konten

Transaktionen

since und until begrenzen createdAt inklusiv. category akzeptiert eine Eltern-ID, die alle zugehörigen Unterkategorien abdeckt.

Kategorien

Kategorien sind von Up festgelegt und können nicht erstellt werden. IDs sind Slugs wie restaurants-and-cafes. Nur Transaktionen mit is_categorizable: true können geändert werden, und nur Blatt-Kategorien werden akzeptiert — die Übergabe einer Eltern-Kategorie wie good-life liefert HTTP 403.

Tags

Eine Transaktion enthält höchstens 6 Tags. Tags, die keiner Transaktion mehr zugeordnet sind, verschwinden aus list_tags.

Anhänge

file_url ist eine signierte URL, die mit file_url_expires_at abläuft. Rufen Sie sie zeitnah ab oder fordern Sie den Anhang erneut an.

Webhooks

secret_key wird nur bei der Erstellung zurückgegeben und nie wieder. Bewahren Sie ihn auf, um den X-Up-Authenticity-Signature-Header (SHA-256-HMAC) bei eingehenden Zustellungen zu verifizieren.

Ressourcen

Beide werden bei Bedarf gelesen und spiegeln den Zustand zum Lesezeitpunkt wider.

Antwort-Konventionen

Aufbau

Up gibt JSON:API zurück, das jedes Feld unter attributes/relationships verschachtelt und auf jeder Ressource Self-Links wiederholt. Dieser Server flacht jede Ressource zu einem kompakten Dict ab und lässt optionale Felder weg, wenn sie fehlen, was die Token-Kosten erheblich reduziert, ohne Informationen zu verlieren, die ein Aufrufer benötigt.

{
  "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
}

Felder wie foreign_amount, hold_info, round_up, cashback, card_purchase_method, note und message erscheinen nur, wenn die Transaktion sie enthält.

Geldbeträge

Jeder Betrag ist ein Objekt:

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

value ist eine Dezimalzeichenfolge, base_units ist die ganzzahlige Untereinheit (Cent für AUD). Abbuchungen sind negativ. Bevorzugen Sie base_units für Berechnungen, um Gleitkommafehler zu vermeiden.

Paginierung

Listen-Tools geben zurück:

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

Zum Blättern übergeben Sie einen zurückgegebenen Cursor als cursor-Argument an dasselbe Tool. Cursor sind Ups eigene opake URLs und kodieren bereits die Filter und die Seitengröße, daher werden alle anderen Argumente ignoriert, wenn cursor gesetzt ist. Ein Null-Cursor bedeutet, dass es keine weitere Seite in dieser Richtung gibt.

Cursors werden vor dem Folgen gegen den konfigurierten API-Host validiert, sodass ein Cursor den Client nicht auf einen anderen Server umleiten kann.

Daten

since und until akzeptieren entweder YYYY-MM-DD oder einen vollständigen RFC-3339-Zeitstempel. Reine Datumsangaben und naive Datums-/Zeitangaben werden an Australia/Sydney gebunden, passend zur Darstellung von Zeiten in der Up-App; für das jeweilige Datum wird der korrekte Offset angewendet, sodass auch die Sommerzeit berücksichtigt wird. Nicht pareisierbare Eingaben werden abgelehnt, bevor die Anfrage gesendet wird, und erscheinen nicht erst als undurchsichtiger HTTP-400-Fehler.

Fehlerbehandlung und Ratenbegrenzung

• API-Fehler werden als ToolError ausgelöst, mit dem HTTP-Status und dem eigenen Fehlertitel und den eigenen Details von Up, zum Beispiel: HTTP 403 — Forbidden: Top-level categories cannot be set directly on transactions.

• 429- und 5xx-Antworten werden bis zu 3 Mal mit exponentiellem Backoff wiederholt; der Retry-After-Header wird berücksichtigt, wenn er vorhanden ist.

• Netzwerkfehler werden nach demselben Zeitplan erneut versucht, bevor sie gemeldet werden.

• Andere 4xx-Antworten als 429 werden nicht erneut versucht — sie weisen auf eine ungültige Anfrage hin.

Projektstruktur

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`

Die Trennung ist beabsichtigt: client.py kennt nur HTTP und nichts über MCP, shapes.py ist eine reine Datentransformation und server.py enthält die Tool-Verträge. Jede Komponente ist unabhängig testbar.

Entwicklung

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

Betreiben Sie den Server prozessintern mit dem 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())

Erstellen Sie das Image nach Änderungen neu:

docker compose up -d --build

Sicherheit

Das Token ist mächtig. Persönliche Zugriffstokens von Up können kein Geld bewegen — die API bietet keinen Zahlungs- oder Überweisungsendpoint —, aber sie können Ihren vollständigen Transaktionsverlauf lesen und Kategorien, Tags und Webhooks ändern. Behandeln Sie ein Token so vertraulich wie ein Passwort.

• Der HTTP-Transport hat keine eigene Authentifizierung. Alles, was den Port erreichen kann, kann Ihre Bankdaten lesen. Compose veröffentlicht den Dienst daher nur auf 127.0.0.1. Binden Sie ihn nicht an 0.0.0.0 und setzen Sie ihn nicht über einen Tunnel oder Reverse-Proxy ein, ohne eine Authentifizierung davorzuschalten.

• Das Token wird niemals in ein Image eingebacken. .env ist in .dockerignore aufgeführt und wird zur Laufzeit bereitgestellt. Es erscheint in keiner Image-Schicht, sodass das Image bedenkenlos in eine Registry gepusht werden kann.

• .env ist gitignoriert, und .env.example enthält nur einen Platzhalter.

• Der Container läuft als Nicht-Root-Benutzer (uid 10001).

• Sofort rotieren, unter https://api.up.com.au/getting_started, falls ein Token jemals offengelegt wurde. Tokens laufen nicht von selbst ab.

Troubleshooting

Referenz

Liste:

• Up-API-Dokumentation

• Up-API-OpenAPI-Spezifikation und Postman-Sammlung

• FastMCP-Dokumentation

• Model Context Protocol-Spezifikation