# Airalo MCP tools

> Every Airalo MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/airalo

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

13 tools for Airalo on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Airalo account (email and password, or Google or Apple sign-in). Airalo emails a verification code on a login from a new device, which you enter once when you connect.
- Integration page: https://cotlet.dev/integrations/airalo-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `airalo_search_packages` | read | eSIM packages from the store for a country or region, with data, validity and price. |
| `airalo_list_esims` | read | eSIMs under My eSIMs, with destination, ICCID and whether they can be topped up. |
| `airalo_get_esim` | read | Details of one eSIM: ICCID, package history, whether it is rechargeable and whether renewals are offered and on. |
| `airalo_get_data_usage` | read | Remaining and used data on an eSIM and when the current package expires. |
| `airalo_get_install_instructions` | read | QR code, SM-DP+ address and activation code to install the eSIM, from Install or share. |
| `airalo_list_topup_packages` | read | Top-up packages available for a rechargeable eSIM, with data, validity and price. |
| `airalo_list_orders` | read | Your orders from Profile > Orders: package, date, amount and order number. |
| `airalo_get_airmoney` | read | Airmoney balance in USD, from Airmoney & Membership. |
| `airalo_buy_esim` | write | Buy a package from search_packages; the eSIM appears under My eSIMs, ready to install. |
| `airalo_top_up_esim` | write | Add a top-up package to a rechargeable eSIM. |
| `airalo_set_renewals` | write | Turn renewals on or off for an eSIM, when it offers them. |
| `airalo_redeem_voucher` | write | Redeem an eSIM voucher code, which adds one package to your account. |
| `airalo_request_refund` | write | Ask for a refund on an eligible order, the same as the Request Refund button. |

## Search packages

MCP tool: `airalo_search_packages`

Access: read.

Returns the packages the Airalo store lists for a destination. Each item has the data amount, validity in days and price in USD, and says whether the eSIM is rechargeable, which Airalo shows under Additional information. Use package_id with buy_esim.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `destination` | string | yes | Country or region, e.g. Japan, Europe, Global. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_search_packages",
    "arguments": {
      "destination": "destination"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "packages": [
      {
        "package_id": "jp-7d-5gb",
        "title": "Japan 5 GB, 7 days",
        "data_gb": 5,
        "validity_days": 7,
        "price_usd": 9.5,
        "rechargeable": true
      },
      {
        "package_id": "jp-30d-10gb",
        "title": "Japan 10 GB, 30 days",
        "data_gb": 10,
        "validity_days": 30,
        "price_usd": 19.5,
        "rechargeable": true
      }
    ]
  },
  "isError": false
}
```

## List my eSIMs

MCP tool: `airalo_list_esims`

Access: read.

Lists the eSIMs in your account with destination, package, ICCID and whether the eSIM is rechargeable. Use esim_id from each item with the other eSIM tools. Set rechargeable_only to see only the eSIMs a top-up can reach.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `rechargeable_only` | boolean | no | Only eSIMs that can be topped up. Default: false. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_list_esims",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esims": [
      {
        "esim_id": "es_48213",
        "destination": "Thailand",
        "package": "Thailand 5 GB, 30 days",
        "iccid": "8910300000000048213",
        "rechargeable": true
      },
      {
        "esim_id": "es_47790",
        "destination": "Japan",
        "package": "Japan 5 GB, 7 days",
        "iccid": "8910300000000047790",
        "rechargeable": false
      }
    ]
  },
  "isError": false
}
```

## Get eSIM details

MCP tool: `airalo_get_esim`

Access: read.

Returns one eSIM as My eSIMs shows it under Details: ICCID, the packages bought for it (Package History) and whether renewals are offered and switched on. Use it before set_renewals.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_get_esim",
    "arguments": {
      "esim_id": "esim_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "destination": "Thailand",
    "iccid": "8910300000000048213",
    "rechargeable": true,
    "renewals": {
      "offered": true,
      "enabled": false
    },
    "package_history": [
      {
        "order_id": "2026100198765",
        "package": "Thailand 5 GB, 30 days"
      }
    ]
  },
  "isError": false
}
```

## Get data usage

MCP tool: `airalo_get_data_usage`

Access: read.

Returns the data bar from My eSIMs: total, used and remaining data and the expiry date. Airalo shows the bar only "if available"; when it is missing, usage_available is false and no numbers come back.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_get_data_usage",
    "arguments": {
      "esim_id": "esim_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "usage_available": true,
    "total_gb": 5,
    "used_gb": 4.2,
    "remaining_gb": 0.8,
    "expires_at": "2026-11-02T23:59:00+07:00"
  },
  "isError": false
}
```

## Get install instructions

MCP tool: `airalo_get_install_instructions`

Access: read.

Returns what Install or share, Share and more shows in the app: a QR code image and the manual installation details (SM-DP+ address, activation code and a confirmation code if Airalo gives one). The tool does not install anything; you scan the QR code or enter the codes on the phone.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_get_install_instructions",
    "arguments": {
      "esim_id": "esim_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "qr_code_url": "https://example.com/qr/es_48213.png",
    "smdp_address": "smdp.example-esim.com",
    "activation_code": "K2-AB12CD-XY34ZW",
    "confirmation_code": null
  },
  "isError": false
}
```

## List top-up packages

MCP tool: `airalo_list_topup_packages`

Access: read.

Returns the top-up packages Airalo offers for one eSIM. The list is empty for an eSIM that is not rechargeable or whose network carrier has changed; in that case you need a new eSIM. Use package_id with top_up_esim.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_list_topup_packages",
    "arguments": {
      "esim_id": "esim_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "packages": [
      {
        "package_id": "th-topup-1gb-7d",
        "title": "Thailand 1 GB, 7 days",
        "price_usd": 2.5
      },
      {
        "package_id": "th-topup-3gb-30d",
        "title": "Thailand 3 GB, 30 days",
        "price_usd": 6.5
      }
    ]
  },
  "isError": false
}
```

## List orders

MCP tool: `airalo_list_orders`

Access: read.

Lists the orders in your account with order number, package, date and amount in USD. Use order_id with request_refund.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `since` | date | no | Only orders on or after this date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_list_orders",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "orders": [
      {
        "order_id": "2026101112345",
        "package": "Japan 5 GB, 7 days",
        "ordered_at": "2026-10-11T08:40:00Z",
        "amount_usd": 9.5
      },
      {
        "order_id": "2026100198765",
        "package": "Thailand 5 GB, 30 days",
        "ordered_at": "2026-10-01T10:05:00Z",
        "amount_usd": 11.5
      }
    ]
  },
  "isError": false
}
```

## Get Airmoney

MCP tool: `airalo_get_airmoney`

Access: read.

Returns your Airmoney balance. Airmoney is tied to US dollars. Airalo applies it at checkout only when the balance is at least 1 USD, and it cannot pay for renewals; applies_at_checkout tells you which side of that line you are on.

### Parameters

No parameters.

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_get_airmoney",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "balance_usd": 4.3,
    "applies_at_checkout": true
  },
  "isError": false
}
```

## Buy eSIM

MCP tool: `airalo_buy_esim`

Access: write. Confirm: waits for the user's OK before it runs.

Prepares the order for one package. Set airmoney_usd to apply Airmoney, which needs a balance of at least 1 USD. When Airalo's checkout needs payment or extra authentication, the tool stops and returns a checkout_url for you to finish; Cotlet never enters card details. Once the order completes, the eSIM appears in My eSIMs and get_install_instructions can follow. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `package_id` | string | yes | Package ID from search_packages. |
| `airmoney_usd` | number | no | Amount of Airmoney to apply, in USD. Default: 0. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_buy_esim",
    "arguments": {
      "package_id": "package_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "2026101112345",
    "package": "Japan 5 GB, 7 days",
    "price_usd": 9.5,
    "airmoney_applied_usd": 2.4,
    "due_usd": 7.1,
    "status": "checkout_required",
    "checkout_url": "https://example.com/checkout/2026101112345"
  },
  "isError": false
}
```

## Top up eSIM

MCP tool: `airalo_top_up_esim`

Access: write. Confirm: waits for the user's OK before it runs.

Adds a package from list_topup_packages to an eSIM you already installed. Set airmoney_usd to apply Airmoney. When Airalo's checkout needs payment or extra authentication, the tool stops and returns a checkout_url for you to finish; Cotlet never enters card details. It fails for an eSIM that is not rechargeable. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |
| `package_id` | string | yes | Top-up package ID from list_topup_packages. |
| `airmoney_usd` | number | no | Amount of Airmoney to apply, in USD. Default: 0. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_top_up_esim",
    "arguments": {
      "esim_id": "es_48213",
      "package_id": "th-topup-3gb-30d",
      "airmoney_usd": 2.4
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "order_id": "2026101112399",
    "package": "Thailand 3 GB, 30 days",
    "price_usd": 6.5,
    "airmoney_applied_usd": 2.4,
    "due_usd": 4.1,
    "status": "checkout_required",
    "checkout_url": "https://example.com/checkout/2026101112399"
  },
  "isError": false
}
```

## Set renewals

MCP tool: `airalo_set_renewals`

Access: write. Confirm: waits for the user's OK before it runs.

Switches the Renewals toggle under My eSIMs, Details. A renewal repeats your original package and is bought when about 10% of the data remains. It cannot be turned on once the data is used up or the validity has ended, and it needs a saved payment method. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `esim_id` | string | yes | eSIM ID from list_esims. |
| `enabled` | boolean | yes | true turns renewals on, false turns them off. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_set_renewals",
    "arguments": {
      "esim_id": "es_48102",
      "enabled": false
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "esim_id": "es_48213",
    "renewals": "off"
  },
  "isError": false
}
```

## Redeem eSIM voucher

MCP tool: `airalo_redeem_voucher`

Access: write. Confirm: waits for the user's OK before it runs.

Redeems an eSIM voucher under Airmoney & Membership, Redeem Voucher. The voucher adds one specific eSIM package to your account, which you then use like any package you bought. A voucher is used up once redeemed. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `code` | string | yes | eSIM voucher code. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_redeem_voucher",
    "arguments": {
      "code": "code"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "status": "redeemed",
    "esim_id": "es_49002",
    "package": "Europe 3 GB, 15 days"
  },
  "isError": false
}
```

## Request refund

MCP tool: `airalo_request_refund`

Access: write. Confirm: waits for the user's OK before it runs.

Requests a refund the way the Request Refund button does under Package History or Profile > Orders. The button appears only for eligible orders, and expired or fully used eSIMs are not eligible; otherwise the call returns an error. Airmoney refunds are instant. Refunds to the original payment method typically take 7 to 10 business days. Several recent automated refunds can send a request to manual review. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `order_id` | string | yes | Order number from list_orders. |
| `reason` | enum | yes | wrong_purchase, plans_changed, installation_issues or esim_not_working. |
| `refund_to` | enum | no | airmoney or original_payment. original_payment only for installation_issues and esim_not_working. Default: airmoney. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "airalo_request_refund",
    "arguments": {
      "order_id": "2026101112345",
      "reason": "wrong_purchase",
      "refund_to": "airmoney"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "order_id": "2026101112345",
    "reason": "wrong_purchase",
    "refund_to": "airmoney",
    "refund_usd": 9.5,
    "status": "refunded"
  },
  "isError": false
}
```