JinDaGe - up-bank-mcp-server MCP Details

article

README

🚀 Up Banking MCP Server

Up Banking MCP Server是一个模型上下文协议（MCP）服务器，可与Up Banking API集成。该服务器允许Claude与你的Up银行数据进行交互，涵盖账户、交易和类别等信息。

🚀 快速开始

本项目可让你使用Claude与Up银行数据交互，你需要完成安装和配置步骤，才能开始使用。

✨ 主要特性

账户管理：列出所有账户，获取账户详细信息和余额。
交易历史：通过灵活的过滤条件（日期范围、状态、类别、标签）查询交易记录。
类别信息：访问Up的消费类别，以便更好地洞察交易情况。
类型安全：使用TypeScript构建，确保可靠性和开发体验。
安全可靠：使用Up的个人访问令牌进行身份验证。

📦 安装指南

安装前提

Node.js 18 或更高版本
拥有Up银行账户
获取Up个人访问令牌

安装步骤

克隆或下载此仓库：

cd up-mcp-server

安装依赖项：

npm install

构建服务器：

npm run build

💻 使用示例

基础用法

配置完成后，你可以向Claude询问以下问题：

"我的当前账户余额是多少？"
"显示我上个月的所有交易记录。"
"我本周在餐厅消费了多少？"
"列出我所有的储蓄账户。"
"我的消费账户中有哪些待处理的交易？"
"显示所有标记为'度假'的交易记录。"

📚 详细文档

获取Up API令牌

打开手机上的Up应用。
向右滑动并选择“数据共享”。
点击“个人访问令牌”。
选择“生成令牌”。
选择令牌的有效期。
按照提示操作，并安全地复制你的令牌。

重要提示：请妥善保管你的令牌！切勿分享或提交到版本控制系统。

配置

Claude桌面配置

将以下内容添加到你的Claude桌面配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "up-banking": {
      "command": "node",
      "args": ["/absolute/path/to/up-mcp-server/build/index.js"],
      "env": {
        "UP_API_TOKEN": "your_up_api_token_here"
      }
    }
  }
}

将/absolute/path/to/up-mcp-server替换为该目录的实际路径，并将your_up_api_token_here替换为你的Up个人访问令牌。

替代方法：使用npx

你也可以直接使用npx运行服务器：

{
  "mcpServers": {
    "up-banking": {
      "command": "npx",
      "args": ["-y", "/absolute/path/to/up-mcp-server"],
      "env": {
        "UP_API_TOKEN": "your_up_api_token_here"
      }
    }
  }
}

可用工具

`up_ping`

测试API连接并验证身份验证是否正常工作。

`up_list_accounts`

列出所有账户，可根据账户类型或所有权进行过滤。参数：

accountType（可选）：按“SAVER”、“TRANSACTIONAL”或“HOME_LOAN”过滤。
ownershipType（可选）：按“INDIVIDUAL”或“JOINT”过滤。

`up_get_account`

获取特定账户的详细信息。参数：

accountId（必需）：账户ID。

`up_list_transactions`

通过全面的过滤选项列出交易记录。参数：

accountId（可选）：过滤到特定账户。
status（可选）：“HELD”（待处理）或“SETTLED”（已结算）。
since（可选）：RFC 3339格式的开始日期（例如，“2024-01-01T00:00:00+10:00”）。
until（可选）：RFC 3339格式的结束日期。
category（可选）：类别ID（例如，“restaurants-and-cafes”）。
tag（可选）：交易标签。
pageSize（可选）：结果数量（1 - 100）。

`up_get_transaction`

获取特定交易的详细信息。参数：

transactionId（必需）：交易ID。

`up_list_categories`

列出Up中的所有消费类别。参数：

parentId（可选）：过滤到特定父类别的子类别。

`up_get_category`

获取特定类别的详细信息。参数：

categoryId（必需）：类别ID（例如，“restaurants-and-cafes”）。

开发

监听模式

在开发过程中实现自动重新编译：

npm run dev

测试连接

配置完成后，重启Claude桌面并尝试以下操作：

Can you ping the Up API to verify the connection?

故障排除

"UP_API_TOKEN environment variable is required"

确保你已将Up API令牌添加到Claude桌面配置的env部分。

"Up API error: 401"

你的API令牌无效或已过期。在Up应用中生成新的令牌。

服务器未在Claude中显示

检查build/index.js的路径是否为绝对路径且正确。
验证配置文件中的JSON语法是否有效。
完全重启Claude桌面。
检查Claude的日志以获取错误消息。

安全注意事项

你的Up API令牌可对银行数据进行完全读取访问。
切勿将令牌提交到版本控制系统。
使用环境变量或安全的配置管理。
可以随时在Up应用中撤销令牌访问权限。
考虑为令牌设置过期日期。

API速率限制

Up API有速率限制。如果超过限制，服务器将返回错误消息。使用分页和过滤功能以减少API调用次数。

贡献

这是一个涵盖主要读取操作的基本实现。潜在的增强功能包括：

添加Webhook支持，实现实时交易通知。
实现交易分类更新。
添加附件/收据支持。
支持基于游标浏览的分页功能。

📄 许可证

本项目采用MIT许可证。

up-bank-mcp-server