ZuckPay MCP

https://github.com/zuckpay/zuckpay-mcp
Admin
Official ZuckPay MCP server that lets AI assistants create PIX, SPEI, and PayPal charges and query...
Tokens:8,508
Snippets:64
Trust Score:2.3
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Development workflow commands

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Install dependencies, run lint/typecheck/tests, build the project, and launch the MCP Inspector for debugging. The build generates dist/index.js (stdio) and dist/http.js (HTTP).

```bash
npm ci
npm run lint && npm run typecheck && npm test
npm run build          # gera dist/index.js (stdio) e dist/http.js (HTTP)
npm run inspector      # debug com o MCP Inspector
```

--------------------------------

### Iniciar servidor HTTP hospedado (npm run start:http)

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Inicia o modo Streamable HTTP stateless para hospedagem multi-tenant. Expõe POST /mcp e GET /healthz na porta $PORT (padrão 8080).

```bash
npm run build && npm run start:http   # POST /mcp + GET /healthz na porta $PORT (padrão 8080)
```

--------------------------------

### GET /healthz

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Health check endpoint for the HTTP server, used for monitoring and orchestration (e.g., Docker HEALTHCHECK).

```APIDOC
## [GET] /healthz

### Description
Health check endpoint for the HTTP server, used for monitoring and orchestration (e.g., Docker HEALTHCHECK).

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- Health status
```

--------------------------------

### Deploy Docker do ZuckPay MCP

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Constrói e executa a imagem Docker alpine com usuário non-root e HEALTHCHECK. Para Railway, o railway.toml já aponta o Dockerfile e o healthcheck.

```bash
docker build -t zuckpay-mcp . && docker run -p 8080:8080 zuckpay-mcp
```

--------------------------------

### getStore

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Your store (showcase): name, slug, template, publication status, and domain.

```APIDOC
## getStore

### Description
Your store (showcase): name, slug, template, publication status, and domain.

### Method
Tool

### Endpoint
getStore

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listProducts

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Lists your products (name, price, status, currency, enabled payment methods).

```APIDOC
## listProducts

### Description
Lists your products (name, price, status, currency, enabled payment methods).

### Method
Tool

### Endpoint
listProducts

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### createPayPalOrder

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Creates a PayPal order in 25 currencies and returns the approval link.

```APIDOC
## createPayPalOrder

### Description
Creates a PayPal order in 25 currencies and returns the approval link.

### Method
Tool

### Endpoint
createPayPalOrder

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### Configure ZuckPay MCP in Claude Desktop or Cursor

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Add this JSON configuration to claude_desktop_config.json or .cursor/mcp.json to register the ZuckPay MCP server. Replace the placeholder credential values with your own.

```json
{
  "mcpServers": {
    "zuckpay": {
      "command": "npx",
      "args": ["-y", "zuckpay-mcp"],
      "env": {
        "ZUCKPAY_CLIENT_ID": "seu_client_id",
        "ZUCKPAY_CLIENT_SECRET": "seu_client_secret"
      }
    }
  }
}
```

--------------------------------

### getProduct

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Details a product by its id.

```APIDOC
## getProduct

### Description
Details a product by its id.

### Method
Tool

### Endpoint
getProduct

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### Conectar cliente MCP via HTTP (Claude Code)

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Adiciona o servidor MCP hospedado ao Claude Code usando autenticação Basic com client_id:client_secret. A tool de saque não é exposta no modo hospedado a menos que ZUCKPAY_ENABLE_WITHDRAW=true.

```bash
claude mcp add --transport http zuckpay https://mcp.zuckpay.com.br/mcp \
  --header "Authorization: Basic $(printf 'seu_client_id:seu_client_secret' | base64)"
```

--------------------------------

### Add ZuckPay MCP server via Claude Code CLI

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Run this command in your terminal to add the ZuckPay MCP server to Claude Code. Replace seu_client_id and seu_client_secret with your actual credentials from the ZuckPay panel.

```bash
claude mcp add zuckpay \
  -e ZUCKPAY_CLIENT_ID=seu_client_id \
  -e ZUCKPAY_CLIENT_SECRET=seu_client_secret \
  -- npx -y zuckpay-mcp
```

--------------------------------

### listWebhooks

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Webhooks configured on the account (URL, events, products, status).

```APIDOC
## listWebhooks

### Description
Webhooks configured on the account (URL, events, products, status).

### Method
Tool

### Endpoint
listWebhooks

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### createPixCharge

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Creates a PIX charge with copy-paste code, QR Code, and hosted checkout. Supports idempotency, split, webhook, and UTMs.

```APIDOC
## createPixCharge

### Description
Creates a PIX charge (copy-paste + QR Code + hosted checkout). Supports idempotency, split, webhook, and UTMs.

### Method
Tool

### Endpoint
createPixCharge

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### Headers de Webhook Assinado (X-ZuckPay-Signature)

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Headers enviados ao endpoint de postback quando a conta possui webhook secret. Valide o body cru e rejeite timestamps antigos (ex.: > 5 min).

```text
X-ZuckPay-Timestamp: <unix_ts>
X-ZuckPay-Signature: t=<unix_ts>,v1=<hex>
```

--------------------------------

### createPixWithdraw

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

PIX withdrawal — only exists with ZUCKPAY_ENABLE_WITHDRAW=true (see Security).

```APIDOC
## createPixWithdraw

### Description
PIX withdrawal — only exists with ZUCKPAY_ENABLE_WITHDRAW=true (see Security).

### Method
Tool

### Endpoint
createPixWithdraw

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### capturePayPalOrder

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Captures the order after the payer approves it.

```APIDOC
## capturePayPalOrder

### Description
Captures the order after the payer approves it.

### Method
Tool

### Endpoint
capturePayPalOrder

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### getSalesToday

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Summary of today's sales: total paid, quantity, average ticket, breakdown by method, and pending.

```APIDOC
## getSalesToday

### Description
Summary of today's sales: total paid, quantity, average ticket, breakdown by method, and pending.

### Method
Tool

### Endpoint
getSalesToday

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listIntegrationKeys

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Metadata of your API keys (name, domain, creation) — never the client_secret.

```APIDOC
## listIntegrationKeys

### Description
Metadata of your API keys (name, domain, creation) — never the client_secret.

### Method
Tool

### Endpoint
listIntegrationKeys

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### getReferralStats

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Your Indicate & Earn: total referrals, pending/released commissions, and history.

```APIDOC
## getReferralStats

### Description
Your Indicate & Earn: total referrals, pending/released commissions, and history.

### Method
Tool

### Endpoint
getReferralStats

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### POST /mcp

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Streamable HTTP endpoint for MCP clients to connect and interact with ZuckPay tools. Each seller authenticates with their own credentials via Basic Auth.

```APIDOC
## [POST] /mcp

### Description
Streamable HTTP endpoint for MCP clients to connect and interact with ZuckPay tools. Each seller authenticates with their own credentials via Basic Auth.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic Auth with base64(client_id:client_secret)

### Response
#### Success Response (200)
- MCP protocol response

### Request Example
```bash
claude mcp add --transport http zuckpay https://mcp.zuckpay.com.br/mcp \
  --header "Authorization: Basic $(printf 'seu_client_id:seu_client_secret' | base64)"
```
```

--------------------------------

### getBalance

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Account balances (available, blocked in release, total) and withdrawal limits.

```APIDOC
## getBalance

### Description
Account balances (available, blocked in release, total) and withdrawal limits.

### Method
Tool

### Endpoint
getBalance

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listCourses

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Lists your courses (membership area): modules, lessons, and number of enrolled students.

```APIDOC
## listCourses

### Description
Lists your courses (membership area): modules, lessons, and number of enrolled students.

### Method
Tool

### Endpoint
listCourses

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listPaymentLinks

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Your payment links (value, method, views, status).

```APIDOC
## listPaymentLinks

### Description
Your payment links (value, method, views, status).

### Method
Tool

### Endpoint
listPaymentLinks

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### createSpeiCashin

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Creates an SPEI charge in MXN and returns the 18-digit CLABE (Mexico).

```APIDOC
## createSpeiCashin

### Description
Creates an SPEI charge in MXN and returns the 18-digit CLABE (Mexico).

### Method
Tool

### Endpoint
createSpeiCashin

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listSubscriptions

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Account subscriptions: product, status (active/cancelled/inactive/pending), value, periodicity.

```APIDOC
## listSubscriptions

### Description
Account subscriptions: product, status (active/cancelled/inactive/pending), value, periodicity.

### Method
Tool

### Endpoint
listSubscriptions

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listAcquirerRoutes

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Acquirer routes available for your account, with conversion rate — the same as in the dashboard.

```APIDOC
## listAcquirerRoutes

### Description
Acquirer routes available for your account, with conversion rate — the same as in the dashboard.

### Method
Tool

### Endpoint
listAcquirerRoutes

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listTransactions

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Lists the account's transactions with filters (status, type, method, period) and cursor pagination.

```APIDOC
## listTransactions

### Description
Lists the account's transactions with filters (status, type, method, period) and cursor pagination.

### Method
Tool

### Endpoint
listTransactions

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### getCardGateways

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Shows the account's card gateways — Stripe (international) and national card (BRL) — with the public keys.

```APIDOC
## getCardGateways

### Description
Shows the account's card gateways — Stripe (international) and national card (BRL) — with the public keys.

### Method
Tool

### Endpoint
getCardGateways

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### listInfractions

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Chargebacks and refund requests (Infractions and MED), with status and deadlines.

```APIDOC
## listInfractions

### Description
Chargebacks and refund requests (Infractions and MED), with status and deadlines.

### Method
Tool

### Endpoint
listInfractions

### Parameters
No parameters documented.

### Response
No response fields documented.
```

--------------------------------

### getTransactionStatus

Source: https://github.com/zuckpay/zuckpay-mcp/blob/main/README.md

Queries the status of a transaction by transactionId or by your external_id_client. Works for PIX, SPEI, and card transactions.

```APIDOC
## getTransactionStatus

### Description
Queries the status of a transaction by transactionId or by your external_id_client. Works for PIX, SPEI, and card transactions.

### Method
Tool

### Endpoint
getTransactionStatus

### Parameters
No parameters documented.

### Response
No response fields documented.
```
Tokens:
Raw