# mcp-iugu

Connects AI assistants to the iugu payment gateway for handling invoices, recurring subscriptions, customer tokens, and marketplace transfers.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/payments/iugu
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-iugu

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `IUGU_API_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-iugu -e IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iugu
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add iugu --env IUGU_API_TOKEN=<IUGU_API_TOKEN> -- npx -y @codespar/mcp-iugu
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "iugu": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-iugu"
            ],
            "env": {
                "IUGU_API_TOKEN": "<IUGU_API_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "iugu": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-iugu"
            ],
            "env": {
                "IUGU_API_TOKEN": "<IUGU_API_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e IUGU_API_TOKEN=<IUGU_API_TOKEN> iugu npx -y @codespar/mcp-iugu
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md