upbank-mcp
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
Related MCP server: Up Bank MCP Server
Requisitos
Cuenta de Up | Un token de acceso personal de https://api.up.com.au/getting_started. Los tokens tienen este formato: |
Docker | Docker Engine 20.10+ con Compose v2 ( |
Python | 3.11+ — solo si se ejecuta fuera de Docker. |
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 --buildEl 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.
Variable | Por defecto | Descripción |
| (obligatorio) | Token de acceso personal. Es la única variable que el servidor lee para las credenciales. Compose se niega a iniciar sin ella; si se ejecuta directamente, el servidor arranca y falla en la primera llamada a una herramienta. |
|
| URL base de la API. Sobrescríbela solo para probar contra un simulacro. |
|
|
|
|
| Dirección de enlace para el transporte HTTP, dentro del contenedor. |
|
| Puerto de escucha para el transporte HTTP, dentro del contenedor. |
|
| Solo para Compose. Puerto del host publicado en |
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 removeEl 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-mcpEstablece 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:latestClaude 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
Herramienta | Parámetros | Devuelve |
| — |
|
Cuentas
Herramienta | Parámetros | Devuelve |
|
| Página de cuentas con saldos. |
|
| Una cuenta. |
Transacciones
Herramienta | Parámetros | Devuelve |
|
| Página de transacciones, de la más reciente a la más antigua. Omite |
|
| Una transacción, incluidos los detalles de retención, redondeo y reembolso. |
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
Herramienta | Parámetros | Devuelve |
|
| El árbol de categorías, o las secundarias de una categoría principal. Sin paginar. |
|
| Una categoría con los ids de su categoría principal y secundarias. |
|
| Establece la categoría, o la elimina cuando |
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
Herramienta | Parámetros | Devuelve |
|
| Página de etiquetas. El id de una etiqueta es su nombre. |
|
| Añade etiquetas, creando las que no existan. |
|
| Elimina etiquetas de la transacción. |
Una transacción admite un máximo de 6 etiquetas. Las etiquetas sin transacciones asociadas desaparecen de list_tags.
Adjuntos
Herramienta | Parámetros | Devuelve |
|
| Página de adjuntos. |
|
| Un adjunto. |
file_url es una URL firmada que caduca en file_url_expires_at. Descárgala de inmediato o vuelve a solicitar el adjunto.
Webhooks
Herramienta | Parámetros | Devuelve |
|
| Página de webhooks. |
|
| Un webhook. |
|
| El nuevo webhook, incluida la |
|
|
|
|
| Envía un evento de prueba |
|
| Intentos de entrega recientes con códigos y cuerpos de respuesta. |
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
URI | Contenido |
| Todas las cuentas y su saldo actual, como una única instantánea JSON. |
| El árbol de categorías completo, para resolver valores de filtro |
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
ToolErrorcon 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-Aftercuando 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 :8000Impulsa 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 --buildSeguridad
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 a0.0.0.0ni 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.
.envestá 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..envestá en gitignore, y.env.examplesolo 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
Síntoma | Causa y solución |
|
|
Compose sale con | Misma causa, detectada al inicio del contenedor en lugar de en la primera llamada. |
| Otro proceso ocupa el puerto 8000. Establece |
| El token no es válido o ha sido revocado. Vuelve a emitirlo. |
| A |
| Los ids son específicos por cliente. Confirma que el id proviene de los datos de este propio token. |
| Límite de tarifa sostenido. Reduce |
El cliente no muestra herramientas | El cliente debe ejecutar el contenedor con |
Referencia
Available Tools
19 toolsadd_tags_to_transactionAdd Tags To TransactionC
Add one or more tags to a transaction.
Inputs: tags (required), transaction_id (required). Returns: object
categorize_transactionCategorize TransactionA
Set or clear a transaction's category.
Only transactions with is_categorizable: true can be changed.
Inputs: transaction_id (required), category_id. Returns: object
create_webhookCreate WebhookA
Register a webhook for transaction events.
The response contains secret_key, which is returned only once — store it now
to verify the X-Up-Authenticity-Signature header on incoming deliveries.
Inputs: url (required), description. Returns: object
delete_webhookDelete WebhookB
Permanently delete a webhook. This cannot be undone.
Inputs: webhook_id (required). Returns: object
get_accountGet AccountC
Retrieve a single account by id.
Inputs: account_id (required). Returns: object
get_attachmentGet AttachmentB
Retrieve a single attachment by id.
Inputs: attachment_id (required). Returns: object
get_categoryGet CategoryB
Retrieve a single category by id.
Inputs: category_id (required). Returns: object
get_transactionGet TransactionB
Retrieve a single transaction by id, including hold, round-up and cashback detail.
Inputs: transaction_id (required). Returns: object
get_webhookGet WebhookC
Retrieve a single webhook by id.
Inputs: webhook_id (required). Returns: object
list_accountsList AccountsB
List the customer's Up accounts with their current balances.
Inputs: cursor, page_size, account_type, ownership_type. Returns: object
list_attachmentsList AttachmentsB
List transaction attachments. File URLs are signed and expire shortly.
Inputs: cursor, page_size. Returns: object
list_categoriesList CategoriesA
List the category tree. Categories are fixed by Up, not user-defined.
Inputs: parent. Returns: object
list_tagsList TagsB
List all tags the customer has created. A tag's id is its label.
Inputs: cursor, page_size. Returns: object
list_transactionsList TransactionsA
List transactions, newest first, optionally filtered by account, status, date range, category or tag.
Inputs: tag, since, until, cursor, +4 more. Returns: object
list_webhook_logsList Webhook LogsA
List recent delivery attempts for a webhook, to debug failing deliveries.
Inputs: webhook_id (required), cursor, page_size. Returns: object
list_webhooksList WebhooksC
List configured webhooks.
Inputs: cursor, page_size. Returns: object
pingPingA
Check that the configured Up API token is valid and the API is reachable.
Inputs: no named parameters. Returns: object
ping_webhookPing WebhookA
Send a test PING event to a webhook to verify it is reachable.
Inputs: webhook_id (required). Returns: object
remove_tags_from_transactionRemove Tags From TransactionC
Remove one or more tags from a transaction.
Inputs: tags (required), transaction_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct resource and action (accounts, transactions, categories, tags, attachments, webhooks), with clear separation between list/get/create/delete/add/remove/ping operations. Overlap is minimal and descriptions explicitly differentiate ambiguous pairs like ping vs ping_webhook.
Nearly all tools follow a consistent snake_case verb_noun pattern (list_accounts, get_transaction, create_webhook, add_tags_to_transaction). The sole minor deviation is 'ping', which lacks a noun but remains unambiguous and predictable.
19 tools across six resource groups is slightly above the typical 3–15 sweet spot, but each tool maps to a distinct, necessary operation for a banking API. No tool appears redundant or trivially thin.
Coverage is broad: full webhook lifecycle plus ping/logs, transaction list/get/categorize, tag add/remove/list, and read operations for accounts, categories, and attachments. Minor gaps exist, notably no attachment upload/delete, but core workflows are otherwise well-covered.
Maintenance
Related MCP Connectors
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseDqualityDmaintenanceA Model Context Protocol server that allows AI assistants to connect to and manage Israeli bank accounts, fetch transactions, and handle authentication for all major Israeli banks and credit card companies.239ISC
- AlicenseNot gradedqualityDmaintenanceAn MCP wrapper for Up Bank's API that allows Claude and other MCP-enabled clients to manage accounts, transactions, categories, tags, and webhooks from Up Bank.3MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables interaction with You Need A Budget (YNAB) via their API, allowing users to manage budgets, accounts, categories, and transactions through natural language.2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows AI assistants to interact with Lunch Money accounts, enabling management of transactions, categories, budgets, and other financial data through natural language commands.20 PyPIMIT