Skip to main content
Glama
ribbo-mcp

ribbo-mcp

by andrespadeto

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 a read-scoped key to only query, or a write-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-mcp

It 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

RIBBO_API_KEY

Your API key (bk_…) from the panel under Developers → API keys. write enables actions; read only runs queries.

RIBBO_API_BASE

Base URL of the API, no trailing slash. Example: https://api.ribbo.app

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

check_entitlements

Queries a customer’s entitlements.

list_subscriptions

Lists the tenant’s subscriptions (filters/pagination).

get_subscription

Shows subscription details.

get_gateway_events

Timeline of how the gateway responded for the charges.

get_payment

Shows payment details.

get_customer_subscriptions

Subscriptions of a customer (by external_id).

get_customer_payments

Payment history of a customer.

get_referral_link

Referral link.

get_renewal_campaign_link

Link of a renewal campaign for a given subscriber.

list_renewal_campaign_links

All links of a campaign.

get_payment_link

Payment link for the open invoice of a subscription.

get_order_payment_link

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

create_subscription

Creates a subscription (including without a card: manual PIX / migration).

change_plan

Changes the plan (upgrade/downgrade/change cycle).

cancel_plan_change

Cancels a scheduled plan change.

cancel_subscription

Cancels the subscription.

charge_now

Triggers the charge for the current invoice immediately.

reschedule_subscription

Reschedules the next charge.

remove_coupon

Removes the coupon from the subscription.

create_renewal_link

Creates a renewal advance link.

create_payment_method_link

Creates a payment method change link.

refund_payment

Refunds a payment.

update_customer

Updates customer name/phone.

update_customer_email

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 read key when the AI only needs to query and a write key 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 + start
  • Source code in src/ (TypeScript ESM). src/index.ts registers the tools; src/api.ts is the HTTP (Bearer) client.

  • The build (dist/) is generated by npm run build and is not versioned.

License

MIT © Ribbo

Available Tools

24 tools
cancel_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_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_paymentC

Detalhe de um pagamento, com a decomposição em items (plano/bump/juros).

Inputs: payment_id (required).

get_subscriptionB

Estado atual de UMA assinatura (qualquer status). Útil para reconciliar um webhook perdido.

Inputs: subscription_id (required).

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

    B3.3/5.0

    Scored across 24 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access Magpie Payment Platform APIs for processing payments, creating checkout sessions, sending invoices, and managing payment links through natural conversation.
      95 npm
      2
      MIT