mcp-airwallex — Claude Code MCP server: payments and payouts
Wires the Airwallex API into your coding agent: 20 tools for pay-ins, refunds, cross-border transfers and FX.
claude mcp add --env AIRWALLEX_CLIENT_ID=<AIRWALLEX_CLIENT_ID> --env AIRWALLEX_API_KEY=<AIRWALLEX_API_KEY> --env AIRWALLEX_ENV=<AIRWALLEX_ENV> --transport stdio airwallex -- npx -y @codespar/mcp-airwallexWhat mcp-airwallex does
This server exposes Airwallex to the agent. It creates and confirms payment intents, supports the two-step auth-then-capture flow, issues full or partial refunds, manages customers and transfer beneficiaries, sends payouts and converts between wallet currencies. One more tool returns the balance for every currency the account holds.
Auth runs on a token. The first call logs in with AIRWALLEX_CLIENT_ID and AIRWALLEX_API_KEY, the token stays cached in memory and is renewed a minute before it lapses. You need an Airwallex account and both keys to start. AIRWALLEX_ENV picks demo or production, and demo is what you get when you leave it out — ship that to production and your requests hit the sandbox.
Every create_* tool demands a request_id used as the idempotency key. The server will not make one up. Pass the same UUID when you retry the same logical operation, otherwise a retry becomes a second payment. That is the part to get right first.
What it helps with
- create a payment intent and capture it in two steps
- refund a captured payment fully or in part
- register a beneficiary with bank details
- send a cross-border transfer and cancel it before settlement
- check the wallet balance in every currency
Example prompts for the agent
- Create a payment intent for 250 USD for customer
cus_123and give me the id - Refund half of captured payment
pi_456 - Show the Airwallex wallet balance across all currencies
How to install mcp-airwallex
Platform CLI
claude mcp add --env AIRWALLEX_CLIENT_ID=<AIRWALLEX_CLIENT_ID> --env AIRWALLEX_API_KEY=<AIRWALLEX_API_KEY> --env AIRWALLEX_ENV=<AIRWALLEX_ENV> --transport stdio airwallex -- npx -y @codespar/mcp-airwallexReplace <…> with your own values
Platform CLI
codex mcp add airwallex --env AIRWALLEX_CLIENT_ID=<AIRWALLEX_CLIENT_ID> --env AIRWALLEX_API_KEY=<AIRWALLEX_API_KEY> --env AIRWALLEX_ENV=<AIRWALLEX_ENV> -- npx -y @codespar/mcp-airwallexReplace <…> with your own values
Config file
{
"mcpServers": {
"airwallex": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-airwallex"
],
"env": {
"AIRWALLEX_CLIENT_ID": "<AIRWALLEX_CLIENT_ID>",
"AIRWALLEX_API_KEY": "<AIRWALLEX_API_KEY>",
"AIRWALLEX_ENV": "<AIRWALLEX_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"airwallex": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-airwallex"
],
"env": {
"AIRWALLEX_CLIENT_ID": "<AIRWALLEX_CLIENT_ID>",
"AIRWALLEX_API_KEY": "<AIRWALLEX_API_KEY>",
"AIRWALLEX_ENV": "<AIRWALLEX_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e AIRWALLEX_CLIENT_ID=<AIRWALLEX_CLIENT_ID> -e AIRWALLEX_API_KEY=<AIRWALLEX_API_KEY> -e AIRWALLEX_ENV=<AIRWALLEX_ENV> airwallex npx -y @codespar/mcp-airwallexReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-airwallex
How do I install mcp-airwallex in Claude Code?
Run claude mcp add mcp-airwallex -e AIRWALLEX_CLIENT_ID=<AIRWALLEX_CLIENT_ID> -e AIRWALLEX_API_KEY=<AIRWALLEX_API_KEY> -- npx -y @codespar/mcp-airwallex. The second variant adds --env and --transport stdio for explicit environment and transport.
What does mcp-airwallex do?
It bridges the agent to Airwallex: payments, refunds, customers, beneficiaries, transfers, FX conversion and balance checks across 20 tools.
What do I need before running it?
An Airwallex client id and API key. Login against /authentication/login fails without them, and every tool call fails with it.
