garu-mcp
OfficialREADME.md
# @garuhq/mcp
[](https://www.npmjs.com/package/@garuhq/mcp)
[](./LICENSE)
An MCP server for the [Garu](https://garu.com.br) payment platform. Create charges, manage customers, and discover products — directly from any MCP client like Claude Desktop, Cursor, or Claude Code.
## Features
- **PIX Charges** — Create instant PIX charges with auto-generated QR codes for Brazilian real-time payments.
- **Boleto Charges** — Generate boleto bancário payment slips.
- **Charge Management** — List, retrieve, and refund charges (full or partial).
- **Products** — List your seller's products and look them up by UUID — the same UUID accepted by the charge tools.
- **Customers** — Create, list, get, update, and remove customers linked to your seller account.
## Setup
Create a Garu account and get your API key at [garu.com.br](https://garu.com.br).
## Usage
### Claude Code
```bash
claude mcp add garu -e GARU_API_KEY=sk_live_xxx -- npx -y --package=@garuhq/mcp@latest garu-mcp
```
### Cursor
Open the command palette and choose "Cursor Settings" > "MCP" > "Add new global MCP server".
```json
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "sk_live_xxx"
}
}
}
}
```
### Windsurf
Add to `.windsurf/mcp.json`:
```json
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "sk_live_xxx"
}
}
}
}
```
### VS Code
Add to `.vscode/mcp.json`:
```json
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "sk_live_xxx"
}
}
}
}
```
### Claude Desktop
Open Claude Desktop settings > "Developer" tab > "Edit Config".
```json
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "sk_live_xxx"
}
}
}
}
```
### Codex
```bash
codex mcp add garu --env GARU_API_KEY=sk_live_xxx -- npx -y --package=@garuhq/mcp@latest garu-mcp
```
## Tools
### Products (5 tools)
| Tool | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_products` | List your seller's products with pagination and search. Each product carries the `pixAutomatic` flag |
| `get_product` | Get a single product by UUID — the identifier accepted by the charge tools. `pixAutomatic` enables Pix Automático on the public subscription checkout |
| `get_product_portal_config` | Read per-product portal customization (B2B2C). Returns `null` if unset — product falls back to seller-level config |
| `set_product_portal_config` | Upsert with merge: only fields provided are written. Pass `null` on a field to inherit from seller |
| `clear_product_portal_config` | Remove the per-product config; product falls back to seller-level config |
> Portal-config tools accept `productId` as either the product UUID (preferred — same id returned by `list_products`) or the legacy numeric id. UUID support added in Garu v0.10.0.
>
> Use `list_products` to discover the UUID you'll pass to `create_pix_charge` or `create_boleto_charge`.
>
> Per-product portal config is the **B2B2C primitive**: SaaS that models professionals/coaches/instructors as Products under one Seller can give each one custom branding (`businessName`, `primaryColor`, `logoUrl`) and policies on the customer payment page + `/minha-area` portal — all without fragmenting the seller's accounting.
### Offers (5 tools)
An offer is a **named price on a product**, reachable at `/pay/{productUuid}?offer={slug or id}`. It overrides the price and nothing else — payment methods, installments, carnê, name, description and image all stay on the product, and a bare product link keeps charging the product's own price.
| Tool | Description |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `list_offers` | List a product's offers. Active only by default; `active: 'all'` includes deactivated ones |
| `get_offer` | Read one offer's current price and whether it is still active |
| `create_offer` | Create an offer. `value` is in **reais**, not centavos, and may exceed the product's own price |
| `update_offer` | Reprice, rename, or activate/deactivate. Deactivating is how you END a promo |
| `delete_offer` | Delete — only while the offer has never sold, otherwise 409 |
> **The slug is public and guessable.** Anyone holding the product link can try `?offer=promo`. For pricing that should not circulate, omit `slug` — the link then carries the unguessable offer id.
>
> **To end a promo, deactivate rather than delete.** A deactivated link falls back to the product's price and tells the buyer the offer ended, so the sale still completes. Deleting is refused once the offer has sales, so past attribution survives.
>
> `create_pix_charge` and `create_boleto_charge` accept an `offer` too — the server resolves the price from it, so the amount is never taken from the agent.
### Charges (5 tools)
| Tool | Description |
| ---------------------- | -------------------------------------------------- |
| `create_pix_charge` | Create a PIX charge with QR code |
| `create_boleto_charge` | Create a boleto bancário charge |
| `list_charges` | List charges with pagination and filters |
| `get_charge` | Get charge details by uuid (includes `status`) |
| `refund_charge` | Refund a charge (full or partial, amount in reais) |
| `cancel_charge` | Cancel an unpaid charge by uuid |
### Customers (6 tools)
| Tool | Description |
| ------------------------------------- | ------------------------------------------------- |
| `create_customer` | Create a customer linked to your seller account |
| `list_customers` | List customers with search and pagination |
| `get_customer` | Get customer details by uuid |
| `update_customer` | Update customer information |
| `delete_customer` | Remove customer from your seller account |
| `set_customer_billing_email_override` | Override the billing-email used for that customer |
### Scheduled charges (13 tools)
Bill an existing customer on a future date — one-time or recurring with card tokenization or Pix Automático (BACEN auto-debit recurring Pix; recurring + `productId` only).
| Tool | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_scheduled_charge` | Schedule a future charge. `type='recurring'` enables silent-charge of saved card on cycle 2+. `methods` accepts `pix_automatic` (Pix Automático — recurring + `productId` only). Optional `maxRecoveryDays` (1–365) caps how long past `dueDate` the recovery sweep keeps auto-billing a missed charge (default 14) |
| `list_scheduled_charges` | Paginated list with filters by status, type, due-date range, customer |
| `get_scheduled_charge` | Detail bundle: charge + event timeline + linked transactions |
| `mark_paid_scheduled_charge` | Mark a cycle paid (off-Garu reconciliation) |
| `charge_now_scheduled_charge` | Force-bill the current cycle now instead of waiting for the due date (same dispatch as the daily cron). Idempotent — reports `already_sent` rather than re-charging |
| `postpone_scheduled_charge` | Move next due date forward |
| `pause_scheduled_charge` / `resume_scheduled_charge` | Suspend / re-enable a series |
| `cancel_recurrence_scheduled_charge` | Hard-stop future cycles (recurring only) |
| `cancel_at_period_end_scheduled_charge` | Stripe-style soft-cancel; reversible |
| `change_scheduled_charge_payment_method` | Swap the saved card |
| `clear_scheduled_charge_payment_method` | Remove saved card; future cycles email-with-link |
| `list_scheduled_charge_attempts` | Per-attempt billing log (v0.8.2). Each row carries the canonical `failureCode` for declines — use this to debug recurring billing failures without joining Transactions |
### Resources
- `garu://docs/quickstart` — Getting started guide
- `garu://docs/openapi` — Link to the OpenAPI spec
### Environment Variables
- `GARU_API_KEY` — Your Garu API key (required). Get yours at [garu.com.br](https://garu.com.br).
## Local Development
1. Clone and build:
```bash
git clone https://github.com/Garu-Pagamentos/garu-mcp.git
npm install
npm run build
```
2. To use the local build, replace the `npx` command with the path to your local build:
**Claude Code:**
```bash
claude mcp add garu -e GARU_API_KEY=sk_live_xxx -- node /absolute/path/to/garu-mcp/dist/index.js
```
**Cursor / VS Code / Windsurf / Claude Desktop:**
```json
{
"mcpServers": {
"garu": {
"command": "node",
"args": ["/absolute/path/to/garu-mcp/dist/index.js"],
"env": {
"GARU_API_KEY": "sk_live_xxx"
}
}
}
}
```
3. Run tests:
```bash
npm test
```
## License
MIT
TDQS
A3.7/5.0
Scored across 37 tools
Disambiguation5/5
Each tool targets a distinct resource and action with clear, detailed descriptions. Tools like pause_scheduled_charge and resume_scheduled_charge are complementary, not overlapping. Even similar operations like retry_webhook_event and resend_webhook_event are carefully differentiated by audit trail semantics.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern in snake_case. Verbs are imperative, nouns are plural for lists and singular for single operations. Even longer names like set_cancel_at_period_end_scheduled_charge adhere to the pattern without deviation.
Tool Count4/5
37 tools is on the higher end but reasonable for a comprehensive payment platform covering customers, charges, scheduled charges, products, webhooks, and setup. Each tool serves a specific purpose, though the scheduled charge cluster (13 tools) could potentially be consolidated slightly.
Completeness4/5
The tool surface is extensive, covering CRUD for customers and charges, lifecycle management for scheduled charges, and webhook handling. A notable gap is the lack of a delete_product tool, as products can only be updated or have their portal config cleared.
Maintenance
ActivityMaintained
ResponsivenessUnresponsive