upbank-mcp

Un servidor de Model Context Protocol que expone la API de Up Banking a clientes de LLM, construido con FastMCP y empaquetado para Docker.

Proporciona 19 herramientas y 2 recursos que cubren toda la superficie pública de la API de Up (cuentas, transacciones, categorías, etiquetas, adjuntos y webhooks), con respuestas rediseñadas para mayor eficiencia de tokens, paginación por cursor conservada de principio a fin y reintento automático ante límites de tasa.

Contenido

• Requisitos

• Inicio rápido

• Configuración

• Ejecutar el servidor

• Conectar un cliente MCP

• Referencia de herramientas

• Recursos

• Convenciones de respuesta

• Gestión de errores y límites de tasa

• Estructura del proyecto

• Desarrollo

• Seguridad

• Solución de problemas

Related MCP server: Up Bank MCP Server

Requisitos

La API de Up está disponible para clientes de Up en Australia. Un token solo concede acceso a los datos del cliente que lo emitió.

Inicio rápido

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

El servidor escucha en http://127.0.0.1:8000/mcp. Verifícalo:

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

Una respuesta correcta incluye tu id de cliente y un emoji de estado:

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

Configuración

Toda la configuración se realiza mediante variables de entorno. Compose lee .env del directorio del proyecto automáticamente.

Ejecutar el servidor

HTTP, mediante Compose

Ideal para un servidor de larga duración compartido por varios clientes en tu máquina.

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

El puerto se publica solo en 127.0.0.1. Consulta Seguridad.

stdio, mediante Docker

Ideal para clientes MCP que inician el servidor como subproceso. Compila la imagen una vez:

docker build -t upbank-mcp:latest .

La imagen usa MCP_TRANSPORT=stdio por defecto, por lo que no se necesita sobrescribir el transporte.

Sin Docker

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

Establece MCP_TRANSPORT=http para servir a través de HTTP en lugar de stdio.

Conectar un cliente MCP

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, o cualquier cliente que use la configuración mcpServers

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

Se requiere -i: el servidor se comunica a través de stdin/stdout. --rm elimina el contenedor cuando el cliente se desconecta.

A través de HTTP

Apunta el cliente a http://127.0.0.1:8000/mcp mientras el stack de Compose esté en ejecución.

Referencia de herramientas

Los parámetros obligatorios están en negrita. Toda herramienta de listado acepta cursor; consulta Paginación.

Utilidades

Cuentas

Transacciones

since y until acotan createdAt de forma inclusiva. category acepta un id de categoría principal, que coincide con todas sus categorías secundarias.

Categorías

Las categorías las fija Up y no se pueden crear. Los ids son slugs como restaurants-and-cafes. Solo se pueden modificar las transacciones con is_categorizable: true, y solo se aceptan categorías hoja; pasar una categoría principal como good-life devuelve el error HTTP 403.

Etiquetas

Una transacción admite un máximo de 6 etiquetas. Las etiquetas sin transacciones asociadas desaparecen de list_tags.

Adjuntos

file_url es una URL firmada que caduca en file_url_expires_at. Descárgala de inmediato o vuelve a solicitar el adjunto.

Webhooks

La secret_key se devuelve solo en la creación y nunca más. Guárdala para verificar la cabecera X-Up-Authenticity-Signature (HMAC SHA-256) en las entregas entrantes.

Recursos

Ambos se leen bajo demanda y reflejan el estado en el momento de la lectura.

Convenciones de respuesta

Forma

Up devuelve JSON:API, que anida cada campo bajo attributes/relationships y repite los self-links en cada recurso. Este servidor aplana cada recurso en un diccionario compacto y omite los campos opcionales cuando no están presentes, lo que reduce de forma significativa el coste de tokens sin perder información que el llamador necesite.

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

Campos como foreign_amount, hold_info, round_up, cashback, card_purchase_method, note y message solo aparecen cuando la transacción los tiene.

Dinero

Cada importe es un objeto:

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

value es una cadena decimal, base_units es la unidad mínima entera (céntimos para AUD). Los cargos son negativos. Para operaciones aritméticas, prefiere base_units para evitar errores de coma flotante.

Paginación

Las herramientas de listado devuelven:

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

Para paginar, pasa el cursor devuelto de vuelta como argumento cursor de la misma herramienta. Los cursores son URLs opacas propias de Up y ya codifican los filtros y el tamaño de página, por lo que se ignoran todos los demás argumentos cuando cursor está establecido. Un cursor nulo significa que no hay más página en esa dirección.

Los cursores se validan contra el host de API configurado antes de seguirse, por lo que un cursor no puede redirigir el cliente a otro servidor.

Fechas

since y until aceptan tanto YYYY-MM-DD como una marca de tiempo RFC-3339 completa. Las fechas solas y las fechas-hora sin zona horaria se anclan a Australia/Sydney, igual que Up presenta las horas en la aplicación; se aplica el desfase correcto para la fecha en cuestión, por lo que el cambio de hora se gestiona automáticamente. La entrada no analizable se rechaza antes de realizar la solicitud, en lugar de aparecer como un HTTP 400 opaco.

Gestión de errores y límites de tarifa

• Los errores de API se lanzan como ToolError con el estado HTTP y el título y detalle de error propios de Up, por ejemplo: HTTP 403 — Forbidden: Top-level categories cannot be set directly on transactions.

• Las respuestas 429 y 5xx se reintentan hasta 3 veces con retroceso exponencial, respetando la cabecera Retry-After cuando está presente.

• Los fallos de red se reintentan con el mismo calendario antes de mostrarse.

• Las respuestas 4xx distintas de 429 no se reintentan: indican una solicitud incorrecta.

Estructura del proyecto

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`

La separación es deliberada: client.py sabe de HTTP y nada de MCP, shapes.py es transformación pura de datos, y server.py contiene los contratos de las herramientas. Cada uno es comprobable de forma independiente.

Desarrollo

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

Impulsa el servidor en proceso con el cliente FastMCP:

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

Reconstruye la imagen después de los cambios:

docker compose up -d --build

Seguridad

El token es potente. Los tokens de acceso personal de Up no pueden mover dinero — la API no tiene endpoint de pago ni de transferencia — pero pueden leer tu historial completo de transacciones y modificar categorías, etiquetas y webhooks. Trátalo como una contraseña.

• El transporte HTTP no tiene autenticación propia. Cualquier cosa que pueda alcanzar el puerto puede leer tus datos bancarios. Por ello, Compose publica solo en 127.0.0.1. No lo vincules a 0.0.0.0 ni lo expongas a través de un túnel o proxy inverso sin poner autenticación delante.

• El token nunca se incrusta en una imagen. .env está listado en .dockerignore, y el token se proporciona en tiempo de ejecución. No aparece en ninguna capa de imagen, por lo que la imagen es segura de subir a un registro.

• .env está en gitignore, y .env.example solo contiene un marcador de posición.

• El contenedor se ejecuta como un usuario no root (uid 10001).

• Rota inmediatamente en https://api.up.com.au/getting_started si un token llega a exponerse. Los tokens no caducan por sí solos.

Solución de problemas

Referencia

• Documentación de la API de Up

• Especificación OpenAPI de la API de Up y colección de Postman

• Documentación de FastMCP

• Especificación del Model Context Protocol