内容
# Wise MCP 服务器
作为 Wise API 的网关，MCP 服务器提供对 Wise 账户管理、转账、汇率、发票和收款人功能的全面访问。
## 使用 Hologram 构建 Wise AI 助手
此 MCP 服务器与 [**hologram-generic-ai-agent-vs**](https://github.com/2060-io/hologram-generic-ai-agent-vs) 完全集成，这是一个用于即时构建去中心化、私有和主权 AI 代理的容器。通过它，您可以将 Wise 助手部署为 Hologram AI 聊天机器人，用户通过安全的 DIDComm 消息传递与之交互 — 无需集中式平台。
[**hologram-verifiable-services**](https://github.com/2060-io/hologram-verifiable-services) 仓库包含一个可直接部署的 **Wise Agent** 配置，该配置将此 MCP 服务器与 Hologram AI 代理捆绑在一起。它包括：
- 预配置的 **代理包**，包含 Wise 特定提示和工具描述
- **多用户令牌支持** — 每个用户提供自己的 Wise API 令牌，安全加密并按会话持久保存
- **Docker Compose** 和 **Kubernetes** 部署配置
- **可验证凭证身份验证** — 用户在访问 Wise 工具之前使用可验证凭证进行身份验证
要开始，请参阅 [wise-agent](https://github.com/2060-io/hologram-verifiable-services/tree/main/wise-agent) 目录。
## 功能
- **账户余额** — 查询多币种余额，包括可用和预留金额
- **汇率** — 获取任意货币对的实时或历史汇率
- **转账历史** — 列出过去的转账，并可按状态、日期和金额筛选
- **转账状态** — 查询特定转账的详细信息
- **收款人** — 列出所有已保存的收款人，按货币筛选
- **发送资金** — 完整的发送流程（报价 → 转账 → 资金划拨），支持 SCA
- **发票** — 创建和发布发票付款请求（商业资料）
- **余额货币** — 列出可用于创建发票的可用余额
- 自动身份验证和个人资料选择（个人或企业）
- **多用户支持** — 在 HTTP 模式下，每个请求都通过 `Authorization` 头部携带自己的令牌，从而允许多个用户共用一个服务器实例
- 支持沙盒和生产环境
- 以 Docker 镜像形式在 Docker Hub 上提供
## 要求
- Python 3.12 或更高版本（仅直接安装时需要）
- `uv` 包管理器（仅直接安装时需要）
- Wise API 令牌
- Docker（如果使用 Docker 镜像）
## 获取 API 令牌
https://wise.com/your-account/integrations-and-tools/api-tokens
在此处创建新的令牌。
## 安装
### 选项 1：直接安装
1. 克隆此仓库：
```bash
git clone https://github.com/2060-io/mcp-wise
cd mcp-wise
```
2. 设置环境：
```bash
cp .env.example .env
# 编辑 .env 以添加您的 Wise API 令牌
```
3. 使用 `uv` 安装依赖项：
```bash
uv venv
uv pip install -e .
```
### 选项 2：使用 Docker Hub
从 Docker Hub 拉取镜像：
```bash
# 最新稳定版本
docker pull io2060/mcp-wise:latest
# 开发版本（最新 main 分支）
docker pull io2060/mcp-wise:dev
```
通过将其添加到您的 `.mcp.json` 中，添加到您的 MCP 客户端：
```json
{
"mcpServers": {
"mcp-wise": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "WISE_API_TOKEN=your_api_token_here",
"-e", "WISE_IS_SANDBOX=true",
"io2060/mcp-wise:latest"
]
}
}
}
```
用您的实际 Wise API 令牌替换 `your_api_token_here`。
### 选项 3：本地构建 Docker
```bash
docker build -t mcp-wise .
```
### 传输模式
服务器支持两种传输模式：
- **stdio**（默认）— 每个用户一个进程，通过 `WISE_API_TOKEN` 环境变量提供令牌
- **streamable-http** — 单个共享服务器，支持企业和终端用户部署模式
提供了模板配置文件：
```bash
# stdio 模式（默认）
cp .mcp.json.stdio .mcp.json
# HTTP 模式
cp .mcp.json.http .mcp.json
```
### 部署模式
在 HTTP 模式下运行（`MODE=http`）时，服务器根据身份验证和访问控制的配置方式支持两种部署模式：
#### 企业模式（单账户）
为此 MCP 服务器实例配置了一个 Wise 账户。服务器配置了全局 API 令牌，并限制了对特定个人资料 ID 的访问。
| 变量 | 值 |
|---|---|
| `WISE_API_TOKEN` | 共享账户的全局 Wise API 令牌 |
| `WISE_ALLOWED_PROFILES` | 允许的个人资料 ID 列表（例如 `12345678,87654321`） |
使用 `list_profiles` 发现个人资料 ID，然后设置 `WISE_ALLOWED_PROFILES` 以控制可访问的个人资料。
```bash
docker run -d --name mcp-wise \
-p 14101:14101 \
-e MODE=http \
-e WISE_API_TOKEN=your_wise_api_token \
-e WISE_ALLOWED_PROFILES=12345678,87654321 \
io2060/mcp-wise:latest
```
#### 终端用户模式（多账户）
服务器 **没有** 全局令牌 — 而是每个 MCP 客户端在 HTTP `Authorization` 头部发送用户令牌：
```text
Authorization: Bearer <wise_api_token>
```
在此模式下，通过个人资料 **类型** 而非 ID 来限制访问。
| 变量 | 值 |
|---|---|
| `WISE_API_TOKEN` | *未设置* |
| `WISE_ALLOWED_PROFILE_TYPES` | 允许的类型列表（默认：`personal`） |
```bash
docker run -d --name mcp-wise \
-p 14101:14101 \
-e MODE=http \
-e WISE_ALLOWED_PROFILE_TYPES=personal,business \
io2060/mcp-wise:latest
```
> **默认行为**：如果未设置 `WISE_ALLOWED_PROFILES` 和 `WISE_ALLOWED_PROFILE_TYPES`，则仅允许 **个人** 个人资料。
客户端使用 streamable-http MCP 传输连接到 `http://localhost:14101/mcp`。
## 可用的 MCP 工具
### `list_profiles`
列出与当前用户 API 令牌关联的所有 Wise 个人资料。未被服务器配置允许的个人资料将被标记为受限。使用此工具发现个人资料 ID 以供其他工具使用。
### `get_balances`
获取 Wise 个人资料的多币种账户余额。
**参数**:
- `profile_id`: Wise 个人资料 ID（使用 `list_profiles` 发现可用 ID）
### `get_exchange_rate`
获取两种货币之间的实时或历史汇率。
**参数**:
- `source_currency`: 源货币代码（例如 'USD'，'EUR'，'GBP'）
- `target_currency`: 目标货币代码（例如 'EUR'，'BRL'，'JPY'）
- `time`: 可选。用于历史汇率的 ISO 8601 时间戳（例如 '2024-06-01T00:00:00Z'）
### `list_transfers`
列出 Wise 个人资料的转账（交易历史）。
**参数**:
- `profile_id`: Wise 个人资料 ID（使用 `list_profiles` 发现可用 ID）
- `status`: 可选。按状态筛选（例如 'processing'，'outgoing_payment_sent'，'cancelled'）
- `limit`: 结果数量（默认：10，最大：100）
- `offset`: 分页偏移量（默认：0）
- `created_date_start`: 可选。ISO 8601 日期筛选器开始
- `created_date_end`: 可选。ISO 8601 日期筛选器结束
### `get_transfer_status`
获取特定转账的详细信息和状态。
**参数**:
- `transfer_id`: 要查询的转账 ID
### `list_recipients`
返回 Wise 个人资料的所有收款人列表。
**参数**:
- `profile_id`: Wise 个人资料 ID（使用 `list_profiles` 发现可用 ID）
- `currency`: 可选。按货币代码筛选收款人（例如 'EUR'，'USD'）
### `send_money`
向收款人发送资金。执行完整流程：创建报价 → 创建转账 → 从余额中提供资金。
**参数**:
- `profile_id`: 要发送资金的 Wise 个人资料 ID（使用 `list_profiles` 发现可用 ID）
- `source_currency`: 源货币代码（例如 'USD'）
- `source_amount`: 源货币中要发送的金额
- `recipient_id`: 要发送资金的收款人 ID
- `payment_reference`: 可选。转账的参考消息（默认为 "money"）
- `source_of_funds`: 可选。资金来源（例如 "salary"， "savings"）
### `create_invoice`
创建发票付款请求。**仅限商业个人资料**。
**参数**:
- `profile_id`: Wise 商业个人资料 ID（使用 `list_profiles` 发现可用 ID）
- `balance_id`: 要用于发票的余额 ID
- `due_days`: 发票到期日数
- `line_items`: 行项目列表，每个包含：
- `name`: 项目名称/描述
- `amount`: 单价金额
- `currency`: 货币代码（必须与余额货币匹配）
- `quantity`: 项目数量
- `tax_name`: 可选税名
- `tax_percentage`: 可选税百分比（0-100）
- `tax_behaviour`: 可选（"INCLUDED" 或 "EXCLUDED"，默认： "EXCLUDED"）
- `payer_name`: 付款人姓名
- `payer_email`: 可选付款人电子邮件
- `payer_address`: 可选地址，包含 `firstLine` 和 `countryIso3Code`
- `payer_locale`: 可选发票 PDF 语言环境（默认： "en"）
- `invoice_number`: 可选（如果未提供，则自动生成）
- `message`: 可选消息（例如税 ID 或公司编号）
- `issue_date`: 可选发行日期，格式为 ISO 8601（默认为今天）
### `get_balance_currencies`
获取可用于创建发票的货币和余额 ID。**仅限商业个人资料**。
**参数**:
- `profile_id`: Wise 商业个人资料 ID（使用 `list_profiles` 发现可用 ID）
## 配置
环境变量（在 `.env` 文件中设置）：
- `WISE_API_TOKEN`: 您的 Wise API 令牌（在 **stdio** 模式下需要；在 **http** 模式下为企业/单账户部署可选，多个用户共享同一个 Wise 账户）
- `WISE_IS_SANDBOX`: 设置为 `true` 以使用 Wise 沙盒 API（默认： `false`）
- `MODE`: MCP 服务器传输模式 — `http`（streamable-http）或 `stdio`（默认： `stdio`）
- `WISE_ALLOWED_PROFILES`: **企业模式** — 允许的 Wise 个人资料 ID 列表。使用 `list_profiles` 发现 ID。示例： `12345678,87654321`。如果设置，则优先于 `WISE_ALLOWED_PROFILE_TYPES`。
- `WISE_ALLOWED_PROFILE_TYPES`: **终端用户模式** — 允许的个人资料类型列表（默认： `personal`）。示例： `personal,business`。仅在未设置 `WISE_ALLOWED_PROFILES` 时使用。
## 开发
### 项目结构
```text
mcp-wise/
├── .env # 环境变量（不提交到 git）
├── .env.example # 示例环境变量
├── pyproject.toml # 项目依赖和配置
├── Dockerfile # Docker 镜像定义
├── README.md # 本文件
└── src/
├── main.py # 入口点
└── wise_mcp/
├── app.py # FastMCP 应用程序设置
├── api/
│ ├── wise_client.py # Wise API 客户端
│ ├── wise_client_helper.py # 个人资料解析助手
│ └── types/ # 数据类类型定义
├── resources/
│ ├── balances.py # 余额工具
│ ├── exchange_rates.py # 汇率工具
│ ├── transfers.py # 转账历史和状态工具
│ ├── recipients.py # 收款人工具
│ ├── send_money.py # 发送资金工具
│ └── invoice_creation.py # 发票工具
└── utils/
└── string_utils.py # 实用函数
```
### 添加新功能
1. 在 `src/wise_mcp/api/wise_client.py` 中添加新的 API 客户端方法
2. 在 `src/wise_mcp/resources/` 中创建新的资源文件
3. 在 `src/wise_mcp/resources/__init__.py` 中导入和注册新工具
### CI/CD
- **合并到 main** → 构建并发布 `io2060/mcp-wise:dev` + 带时间戳的 `dev-YYYYMMDD-HHMMSS` 标签到 Docker Hub
- **发布** → 由 [release-please](https://github.com/googleapis/release-please) 管理；合并发布 PR 后发布 `io2060/mcp-wise:latest` + 版本标签
## 贡献
欢迎贡献！请随时提交拉取请求。
## 许可证
MIT
