io.github.codespar/mcp-iugu MCP Server

This MCP server for iugu provides tools for invoices, subscriptions, and payment management, covering payment methods and related entities like customers. It is designed for use via Model Context Protocol (MCP) and is positioned for Brazilian/Latin America payment workflows, including Pix and open finance concepts.

🛠️ Key Features

MCP server for iugu
Invoice management
Subscription management
Payment management (includes payment methods and customers)
Topics include: payments, pix, nfe, and open-finance

🚀 Use Cases

Automate invoice and subscription workflows through LLM tool calls
Manage customer payment methods and payment actions for Brazilian/Latin America operations
Build agent integrations labeled for agentic-commerce and fintech contexts

⚡ Developer Benefits

Works with MCP
Integrates with Claude Desktop via MCP configuration
Requires IUGU_API_TOKEN environment variable for access

⚠️ Limitations

Server setup example shown only for Claude Desktop
Provided material does not specify available tool names or counts beyond the functional scope described

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "iugu": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-iugu"],
      "env": {
        "IUGU_API_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

bash

claude mcp add iugu -- npx @codespar/mcp-iugu

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

json

{
  "servers": {
    "iugu": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-iugu"],
      "env": {
        "IUGU_API_TOKEN": "your-token"
      }
    }
  }
}

Tools (23)

Tool

Purpose

create_invoice

Create an invoice in iugu (Pix, boleto, or credit card)

get_invoice

Get invoice details by ID

list_invoices

List invoices with optional filters

cancel_invoice

Cancel (delete) an invoice.

refund_invoice

Refund a paid invoice (full or partial).

duplicate_invoice

Duplicate an existing invoice with a new due date.

create_customer

Create a customer in iugu

update_customer

Update a customer.

list_customers

List customers with optional filters

create_plan

Create a subscription plan (recurring template).

update_plan

Update an existing plan.

list_plans

List subscription plans.

create_subscription

Create a recurring subscription in iugu

suspend_subscription

Suspend a subscription.

activate_subscription

Reactivate a suspended subscription.

cancel_subscription

Cancel (delete) a subscription.

create_payment_token

Tokenize a credit card server-side.

create_payment_method

Attach a payment method (credit card token) to a customer.

create_subaccount

Create a marketplace sub-account.

create_transfer

Transfer funds between iugu accounts (marketplace).

request_withdraw

Request a bank withdrawal (saque) from a sub-account.

create_webhook

get_account_info

Get account information, configuration, and balance

Variable

Required

Description

IUGU_API_TOKEN

Yes

API token from iugu dashboard

IUGU_SANDBOX

Set to "true" for test mode

Roadmap

v0.3 (planned)

create_split — Create split payment rules

list_transfers — List marketplace transfers

get_financial_report — Financial summary report

batch_invoices — Create multiple invoices in a single request

list_payment_methods — List saved payment methods for a customer

Install

Configuration

Environment variables

IUGU_API_TOKENrequiredsecret

API key for iugu

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-iugu": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-iugu@0.2.2"
      ],
      "env": {
        "IUGU_API_TOKEN": "<YOUR_IUGU_API_TOKEN>"
      }
    }
  }
}

io.github.codespar/mcp-iugu