ribbo-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ribbo-mcp List all active subscriptions and flag any with failed payments."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ribbo-mcp
Ribbo's MCP (Model Context Protocol) server. It connects your AI assistant (Claude Desktop, Cursor, etc.) to Ribbo’s recurring billing API and turns it into an operator: the AI now performs real actions — create and manage subscriptions, query entitlements, refund payments, charge right away, and generate payment/renewal links.
Authentication uses your tenant API key (bk_ prefix), generated in the dashboard under Developers → API keys. The server is a thin client of the public API: no secret lives in the code — you supply your key through an environment variable.
Requirements
Node.js 18+
A Ribbo API key (
bk_…). Use aread-scoped key to only query, or awrite-scoped key so the AI can take action (issue refunds, charge, cancel, etc.).
Related MCP server: Agent Billy MCP Server
Installation
The fastest way — without cloning anything — is to point your AI client at the package via npx. To test in your terminal:
# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp
# ou, depois de publicado no npm:
npx -y ribbo-mcpIt stays waiting on stdio — that's how an MCP server works. The client that actually "talks" to it is your AI client (see below), not the terminal. To quit, press:
Ctrl+C.
Configuration
Two environment variables:
Variable | Description |
| Your API key ( |
| Base URL of the API, no trailing slash. Example: |
Claude Desktop
In claude_desktop_config.json (menu → Settings → Developer → Edit Config):
{
"mcpServers": {
"ribbo": {
"command": "npx",
"args": ["-y", "github:andrespadeto/ribbo-mcp"],
"env": {
"RIBBO_API_KEY": "bk_sua_chave_aqui",
"RIBBO_API_BASE": "https://api.ribbo.app"
}
}
}
}Restart Claude Desktop. The Ribbo tools appear in the chat’s tools icon.
Cursor
Using .cursor/mcp.json (in the project) or the global MCP settings, use the same mcpServers block above.
After it is published to npm, replace
"github:andrespadeto/ribbo-mcp"with"ribbo-mcp".
Tools
Reading (a read key is enough):
Tool | What it does |
| Queries a customer’s entitlements. |
| Lists the tenant’s subscriptions (filters/pagination). |
| Shows subscription details. |
| Timeline of how the gateway responded for the charges. |
| Shows payment details. |
| Subscriptions of a customer (by |
| Payment history of a customer. |
| Referral link. |
| Link of a renewal campaign for a given subscriber. |
| All links of a campaign. |
| Payment link for the open invoice of a subscription. |
| 2nd copy / re-access to the PIX for an order (one-off purchase or renewal advance). |
Writing (requires a write key — moves money/state):
Tool | What it does |
| Creates a subscription (including without a card: manual PIX / migration). |
| Changes the plan (upgrade/downgrade/change cycle). |
| Cancels a scheduled plan change. |
| Cancels the subscription. |
| Triggers the charge for the current invoice immediately. |
| Reschedules the next charge. |
| Removes the coupon from the subscription. |
| Creates a renewal advance link. |
| Creates a payment method change link. |
| Refunds a payment. |
| Updates customer name/phone. |
| Updates the customer’s email (local + gateway). |
Security
The key identifies and isolates your tenant — data from other tenants is never accessible.
The write tools move money/state (refund, charge, cancel). Use a
readkey when the AI only needs to query and awritekey only where it should act.The key lives in the MCP client’s
env(on your machine) — treat it as a secret; never commit it.The code is open source and contains no secrets: every credential comes from the environment.
API Conventions
Money is in cents (integer); IDs have a prefix (sub_, cus_, pay_, ord_…); dates are in ISO-8601 UTC. Errors come back as Erro <status>: {…}. The full contract (OpenAPI 3.1) is available at GET {RIBBO_API_BASE}/v1/public/schema/.
Development
git clone https://github.com/andrespadeto/ribbo-mcp.git
cd ribbo-mcp
npm install # o "prepare" compila o TypeScript para dist/
cp .env.example .env # preencha RIBBO_API_KEY e RIBBO_API_BASE
npm run dev # build + startSource code in
src/(TypeScript ESM).src/index.tsregisters the tools;src/api.tsis the HTTP (Bearer) client.The build (
dist/) is generated bynpm run buildand is not versioned.
License
MIT © Ribbo
Available Tools
24 toolscancel_plan_changeA
Cancela uma troca de plano AGENDADA. 422 se não houver troca agendada. Escopo write.
Inputs: subscription_id (required).
cancel_subscriptionB
Cancela uma assinatura (terminal, idempotente). 422 se houver QR Pix pagável. Escopo write.
Inputs: subscription_id (required), reason.
change_planA
Troca o plano de uma assinatura (upgrade imediato com proração; downgrade/troca de ciclo agendados). Escopo write.
Inputs: offer_slug (required), subscription_id (required), keep_coupon.
charge_nowC
Enfileira uma cobrança imediata no cartão salvo da assinatura (202). Escopo write.
Inputs: subscription_id (required).
check_entitlementsA
Consulta as capacidades (entitlements) das assinaturas vivas de um cliente — o que liberar no seu SaaS. Informe external_id OU email.
Inputs: email, external_id.
create_payment_method_linkA
Gera um link para o cliente trocar de forma de pagamento (cartão/Pix), sem cobrança, single-use, 7 dias. Escopo write.
Inputs: subscription_id (required).
create_renewal_linkC
Gera um link de renovação avulsa (expira em 7 dias). Escopo write.
Inputs: subscription_id (required), offer_slug, price_cents.
create_subscriptionA
Cria uma assinatura SEM cartão (Pix manual ou migração). Idempotente por (cliente, oferta). Escopo write.
Inputs: offer_slug (required), external_id (required), doc, name, +6 more.
get_customer_paymentsB
Histórico de pagamentos de um cliente (recorrente + avulso), paginado por cursor.
Inputs: external_id (required), after, limit.
get_customer_subscriptionsB
Todas as assinaturas de um cliente (qualquer status), pelo seu external_id.
Inputs: external_id (required).
get_gateway_eventsB
Timeline do que o gateway respondeu para uma assinatura (aprovação/recusa/estorno/chargeback).
Inputs: subscription_id (required).
get_order_payment_linkB
Link de re-acesso ao Pix de um pedido pendente (compra avulsa OU adiantamento de renovação) — a 2ª via para reenviar ao cliente. 409 se não há Pix pendente para reabrir.
Inputs: order_id (required).
get_paymentC
Detalhe de um pagamento, com a decomposição em items (plano/bump/juros).
Inputs: payment_id (required).
get_payment_linkB
Link público de pagamento da fatura EM ABERTO de uma assinatura. 409 se não há fatura aberta.
Inputs: subscription_id (required).
get_referral_linkB
Código/link de indicação de um cliente + recompensa e progresso. Informe external_id OU email.
Inputs: email, external_id.
get_renewal_campaign_linkA
Link de renovação de um cliente numa campanha (cria-ou-obtém, idempotente). Exige escopo write.
Inputs: campaign_id (required), external_id (required).
get_subscriptionB
Estado atual de UMA assinatura (qualquer status). Útil para reconciliar um webhook perdido.
Inputs: subscription_id (required).
list_renewal_campaign_linksC
Lista todos os links de uma campanha de renovação (cursor).
Inputs: campaign_id (required), after, limit.
list_subscriptionsB
Lista as assinaturas do tenant. Filtros opcionais por status (CSV), offer_slug, e paginação por cursor (limit, after).
Inputs: after, limit, status, offer_slug.
refund_paymentC
Estorna um pagamento (total/parcial). Se atingir runway pré-pago, retorna 422 requires_confirmation=runway; reenvie com confirm_runway=true. Escopo write.
Inputs: reason (required), payment_id (required), amount_cents (required), revoke, +1 more.
remove_couponB
Remove o cupom dos ciclos futuros de uma assinatura. Escopo write.
Inputs: subscription_id (required).
reschedule_subscriptionA
Reagenda a próxima cobrança (NÃO cobra). next_billing_at deve ser futuro (ISO-8601). Escopo write.
Inputs: next_billing_at (required), subscription_id (required).
update_customerB
Atualiza nome/email/telefone de um cliente (doc e external_id não são editáveis). Escopo write.
Inputs: external_id (required), name, email, phone.
update_customer_emailC
Atualiza o e-mail de um cliente (sincroniza com o gateway). Escopo write.
Inputs: email (required), external_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct resource and action, with clear boundaries between similar operations like get_payment_link (subscription invoice) and get_order_payment_link (one-off Pix order). Detailed descriptions further prevent ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_subscriptions, create_renewal_link, refund_payment). The few compound names like get_gateway_events still fit the pattern with nested nouns.
24 tools is on the higher end for a single server, but the breadth is justified by the comprehensive billing domain (subscriptions, payments, customers, links). It remains manageable and each tool has a specific purpose.
The core subscription and payment lifecycles are well covered, but there are notable gaps: no get_customer or create_customer, no apply_coupon or add_coupon, no direct payment method management beyond a link, and no way to list all payments for a subscription. These create dead ends for some workflows.
Related MCP Connectors
Stripe payments for AI agents. Create links, verify, manage customers.
Manage GoCardless payments, mandates, subscriptions, refunds and payouts via AI assistants.
Give AI agents secure access to RevDesk calling, SMS, phone numbers, caller IDs, and usage.
Track, analyze, and act on your streaming and SaaS subscriptions from any AI agent.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with GoCardless payment data, providing tools to manage customers, payments, mandates, subscriptions, and payouts. Includes Xero integration support for automatic parsing of metadata.12MIT
- AlicenseNot gradedqualityDmaintenanceProvides secure, role-based access to Stripe billing operations for AI assistants like Claude and Cursor. It enables users to manage customers, subscriptions, invoices, and refunds through a local proxy with server-side permission enforcement.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access Magpie Payment Platform APIs for processing payments, creating checkout sessions, sending invoices, and managing payment links through natural conversation.95 npm2MIT

Revenium MCP Serverofficial
AlicenseCqualityBmaintenanceConnects AI agents to Revenium for cost tracking, alerting, and usage-based billing, enabling AI assistants to manage costs, set alerts, and handle billing operations.7MIT