mcp-iugu — Claude Code MCP server: what it does, how to install
Connects AI assistants to the iugu payment gateway for handling invoices, recurring subscriptions, customer tokens, and marketplace transfers.
claude mcp add mcp-iugu -e IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iuguWhat mcp-iugu does
The @codespar/mcp-iugu package links coding assistants to iugu services through 23 tools. It generates invoices for Pix, boleto, and credit cards. Agents can duplicate charges, process refunds, edit customer records, and tokenize cards directly server-side.
The server also covers recurring billing and marketplace setups. Assistants can configure subscription plans, pause recurring charges, set up sub-accounts, and register webhooks. Requesting bank payouts is also supported.
Running this integration requires setting the IUGU_API_TOKEN environment variable. Without this token, calls fail authentication. To avoid charging real bank accounts during development, set IUGU_SANDBOX="true" alongside a test-mode API key.
What it helps with
- generate payment invoices with Pix, boleto, or credit cards
- process full or partial refunds on settled invoices
- manage recurring billing plans and pause subscriptions
- transfer funds between marketplace sub-accounts
- set up webhooks for gateway payment notifications
Example prompts for the agent
- Create a Pix invoice for 120 BRL assigned to customer cus_987
- Suspend subscription sub_abc123 and report the account balance
- Refund the payment on invoice inv_555 partially
How to install mcp-iugu
Platform CLI
claude mcp add mcp-iugu -e IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iuguReplace <…> with your own values
Platform CLI
codex mcp add iugu --env IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iuguReplace <…> with your own values
Config file
{
"mcpServers": {
"iugu": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-iugu"
],
"env": {
"IUGU_API_TOKEN": "<IUGU_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"iugu": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-iugu"
],
"env": {
"IUGU_API_TOKEN": "<IUGU_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e IUGU_API_TOKEN=<IUGU_API_TOKEN> iugu npx -y @codespar/mcp-iuguReplace <…> 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-iugu
How to install mcp-iugu in Claude Code?
Run claude mcp add mcp-iugu -e IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iugu in your terminal, replacing <IUGU_API_TOKEN> with your key.
What operations does mcp-iugu cover?
It provides 23 tools for creating invoices, managing customer records, running subscription plans, issuing refunds, and controlling marketplace sub-accounts.
How can I test mcp-iugu without real charges?
Generate an API token inside the iugu test dashboard and pass the IUGU_SANDBOX="true" environment variable.
