upbank-mcp

一个将 Up Banking API 暴露给 LLM 客户端的 Model Context Protocol 服务器，使用 FastMCP 构建并打包为 Docker。

它提供 19 个工具 和 2 个资源，覆盖 Up API 的完整公开表面——账户、交易、类别、标签、附件和 Webhook——响应针对 token 效率进行了重塑，游标分页端到端保留，并在速率限制时自动重试。

目录

• 要求

• 快速开始

• 配置

• 运行服务器

• 连接 MCP 客户端

• 工具参考

• 资源

• 响应约定

• 错误处理与速率限制

• 项目结构

• 开发

• 安全

• 故障排除

Related MCP server: Up Bank MCP Server

要求

Up API 可供澳大利亚的 Up 客户使用。令牌仅授予对签发客户自身数据的访问权限。

快速开始

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

服务器监听于 http://127.0.0.1:8000/mcp。验证它：

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

健康的响应包含你的客户 id 和一个状态表情符号：

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

配置

所有配置均通过环境变量进行。Compose 会自动从项目目录读取 .env。

运行服务器

HTTP，通过 Compose

最适合在你的机器上由多个客户端共享的长期运行服务器。

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

端口仅发布在 127.0.0.1 上。参见 安全。

stdio，通过 Docker

最适合将服务器作为子进程启动的 MCP 客户端。构建镜像一次：

docker build -t upbank-mcp:latest .

镜像默认使用 MCP_TRANSPORT=stdio，因此无需覆盖传输设置。

不使用 Docker

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

设置 MCP_TRANSPORT=http 以通过 HTTP 提供服务，而非 stdio。

连接 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，或任何使用 mcpServers 配置的客户端

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

-i 是必需的——服务器通过 stdin/stdout 通信。--rm 在客户端断开连接时清理容器。

通过 HTTP

在 Compose 栈运行时，将客户端指向 http://127.0.0.1:8000/mcp。

工具参考

必需参数为粗体。每个列表工具都接受 cursor；参见 分页。

工具

账户

交易

since 和 until 以闭区间约束 createdAt。category 接受父 id，该 id 会匹配其所有子类别。

类别

类别由 Up 固定，无法创建。Id 是诸如 restaurants-and-cafes 的 slug。只有 is_categorizable: true 的交易才能被更改，并且只接受叶子类别——传递诸如 good-life 的父类别会返回 HTTP 403。

标签

一笔交易最多持有 6 个标签。没有剩余交易的标签会从 list_tags 中消失。

附件

file_url 是一个签名 URL，在 file_url_expires_at 时过期。请及时获取，或重新请求附件。

Webhook

secret_key 仅在创建时返回，之后不再返回。请存储它，以验证传入投递上的 X-Up-Authenticity-Signature 头（SHA-256 HMAC）。

资源

两者均按需读取，反映读取时的状态。

响应约定

形状

Up 返回 JSON:API，它将每个字段嵌套在 attributes/relationships 下，并在每个资源上重复自链接。本服务器将每个资源扁平化为紧凑的 dict，并在可选字段不存在时省略它们，这显著降低了 token 成本，同时不丢失调用者所需的信息。

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

诸如 foreign_amount、hold_info、round_up、cashback、card_purchase_method、note 和 message 等字段仅在交易具有它们时出现。

金额

每个金额都是一个对象：

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

value 是十进制字符串，base_units 是整数最小单位（AUD 为分）。借记为负数。 进行算术运算时优先使用 base_units，以避免浮点错误。

分页

列表工具返回：

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

要翻页，请将返回的游标作为同一工具的 cursor 参数传入。 游标是 Up 自己的不透明 URL，已经编码了过滤条件和页面大小，因此 当设置了 cursor 时，所有其他参数都会被忽略。cursor 为 null 表示该方向 没有更多页面。

游标在跟随前会针对配置的 API 主机进行验证，因此 游标无法将客户端重定向到其他服务器。

日期

since 和 until 接受 YYYY-MM-DD 或完整的 RFC-3339 时间戳。裸 日期和 naive 日期时间会锚定到 Australia/Sydney，这与 Up 在应用中的展示方式一致；对于所涉日期会应用正确的偏移量， 因此夏令时也能正确处理。无法解析的输入会在请求发出前被拒绝， 而不是在发出后以不透明的 HTTP 400 形式浮出。

错误处理与速率限制

• API 错误会以 ToolError 形式抛出，包含 HTTP 状态码以及 Up 自己的错误标题 和详细信息，例如： HTTP 403 — Forbidden: Top-level categories cannot be set directly on transactions.

• 429 和 5xx 响应会以指数退避方式重试最多 3 次， 并在存在 Retry-After 头时予以遵循。

• 网络故障会在浮出前按相同计划重试。

• 除 429 之外的 4xx 响应不会重试——它们表示请求有误。

项目结构

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`

这种分离是刻意的：client.py 只了解 HTTP，与 MCP 无关； shapes.py 是纯粹的数据转换；server.py 持有工具契约。 每个模块都可以独立测试。

开发

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

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

更改后重建镜像：

docker compose up -d --build

安全

令牌威力强大。 Up 个人访问令牌不能移动资金——API 没有 支付或转账端点——但它们可以读取你的完整交易 历史，并修改类别、标签和 Webhook。请像对待密码一样对待它。

• HTTP 传输本身没有认证。 任何能访问 该端口的人都可以读取你的银行数据。因此 Compose 只发布到 127.0.0.1。除非在它前面加上认证，否则不要将其绑定到 0.0.0.0， 也不要通过隧道或反向代理暴露它。

• 令牌绝不会被烘焙进镜像。 .env 被列在 .dockerignore 中， 令牌在运行时提供。它不会出现在任何镜像层中，因此 该镜像可以安全地推送到注册表。

• .env 已被 gitignore，.env.example 只包含占位符。

• 容器以非 root 用户运行（uid 10001）。

• 如果令牌曾经暴露，请立即轮换，参见 https://api.up.com.au/getting_started。 令牌不会自行过期。

故障排除

参考

• Up API 文档

• Up API OpenAPI 规范与 Postman 集合

• FastMCP 文档

• Model Context Protocol 规范