ribbo-mcp

". Fine.

Now, ensure table in "Config" has space before "Dos variables". Good.

Now, let's generate the output in final message. We need to be mindful of Markdown tables rounding: If we use "| ---------- |", the table renders. Good.

Let's produce final text now. Remember not to add period or commentary.# ribbo-mcp

Servidor MCP (Model Context Protocol) de Ribbo. Conecta tu asistente de IA (Claude Desktop, Cursor, etc.) a la API de cobro recurrent de Ribbo y lo convierte en un operador: la IA pasa a ejecutar acciones reales — crear y gestionar suscripciones, consultar entitlements, reembolsar pagos, cobrar al momento y generar enlaces de pago/renovación.

Autenticación mediante tu API key de tenant (prefijo bk_), generada en el panel en Desarrolladores → API keys. El servidor es un cliente ligero de la API: ningún secreto queda en el código — tú proporcionas tu clave por la variable de entorno.

Requisitos

• Node.js 18+

• Una API key de Ribbo (bk_…). Usa una clave con alcance read para solo consultar, o write para que la IA actúe (reembolsar, cobrar, cancelar, etc.).

Related MCP server: Agent Billy MCP Server

Instalación

La forma más rápida — sin clonar nada — es apuntar tu cliente de IA al paquete mediante npx. Para probarlo en el terminal:

# direto do GitHub (funciona já):
npx -y github:andrespadeto/ribbo-mcp

# ou, depois de publicado no npm:
npx -y ribbo-mcp

Permanece en espera en stdio — así es como ejecuta una MCP. Quien "conversa" con él es tu cliente de IA (abajo), no el terminal. Para salir: Ctrl+C.

Configuración

Dos variables de entorno:

Claude Desktop

En claude_desktop_config.json (menú → 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"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de Ribbo aparecen en el icono de herramientas del chat.

Cursor

En .cursor/mcp.json (en el proyecto) o en la configuración global de MCP, usa el mismo bloque mcpServers de arriba.

Después de publicar en npm, sustituye "github:andrespadeto/ribbo-mcp" por "ribbo-mcp".

Herramientas

Lectura (basta con clave read):

Escritura (requieren clave write — mueven dinero/estado):

Seguridad

• La clave identifica y aísla tu tenant — los datos de otros tenants nunca están accesibles.

• Las herramientas de escritura mueven dinero (realizar, cobro, cancelación). Usa una clave read cuando solo necesita consultar, y una write únicamente para actuar.

• La clave vive en el env del cliente MCP (en tu equipo) — trátala como un secreto; nunca la hagas commit.

• El código es abierto y no contiene secretos: todas las credenciales vienen del entorno.

Convenciones de la API

Dinero en centavos (entero); IDs con prefijo (sub_, cus_, pay_, ord_…); fechas en ISO-8601 UTC. Los errores llegan como Erro <status>: {…}. El contrato completo (OpenAPI 3.1) está en el ejemplo GET {RIBBO_API_BASE}/v1/public/schema/.

Desarrollo

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

• Código en src/ (TypeScript ESM). src/index.ts registra las herramientas; src/api.ts es el cliente HTTP (Bearer).

• El build (dist/) se genera con npm run build y no se destruye.

Licencia

MIT © Ribbo