ribbo-mcp

MCP-Server (Model Context Protocol) von Ribbo. Er verbindet Ihren KI-Assistenten (Claude Desktop, Cursor usw.) mit der API für wiederkehrende Zahlungen von Ribbo und macht ihn zu einem Operator: Die KI kann echte Aktionen ausführen — Abonnements erstellen und verwalten, Entitlements abfragen, Zahlungen erstatten, sofort abrechnen und Links für Zahlung/Verlängerung erzeugen.

Die Authentifizierung erfolgt über Ihren Tenant-API-Key (Präfix bk_), der im Dashboard unter Entwickler → API keys erstellt wird. Der Server ist ein schlanker Client der öffentlichen API: keine Geheimnisse liegen im Code — Sie geben Ihren Schlüssel über eine Umgebungsvariable an.

Voraussetzungen

• Node.js 18+

• Einen Ribbo-API-Key (bk_…). Verwenden Sie einen Schlüssel mit read-Scope, um nur zu lesen, oder write, damit die KI handeln kann (erstatten, abbuchen, kündigen usw.).

Related MCP server: Agent Billy MCP Server

Installation

Der schnellste Weg — ohne etwas zu klonen — ist, Ihren KI-Client über npx auf das Paket zu zeigen. Zum Testen im Terminal:

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

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

Er wartet auf stdio — so läuft ein MCP-Server. Wer mit ihm „spricht“, ist Ihr KI-Client (unten), nicht das Terminal. Zum Beenden: Ctrl+C.

Konfiguration

Zwei Umgebungsvariablen:

Claude Desktop

In 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"
      }
    }
  }
}

Reinicie o Claude Desktop. Die Ribbo-Tools erscheinen im Tool-Icon des Chats.

Cursor

In .cursor/mcp.json (im Projekt) oder in den globalen MCP-Einstellungen verwenden Sie denselben mcpServers-Block wie oben.

Nach der Veröffentlichung auf npm ersetzen Sie "github:andrespadeto/ribbo-mcp" durch "ribbo-mcp".

Tools

Lesen (der read-Schlüssel reicht):

Schreiben (erfordert write-Schlüssel — bewegt Geld/Status):

Sicherheit

• Der Schlüssel identifiziert und isoliert Ihren Tenant — Daten von anderer? tenant können nicht zugegriffen werden.

• Die Schreibwerkzeuge bewegen Geld/Status (Erstattung, Zahlung, Kündigung). Verwenden Sie einen read-Schlüssel, wenn die KI nur abfragen soll, und einen write-Schlüssel nur dort, wo sie handeln soll.

• Der Schlüssel liegt in den Umgebungsvariablen des MCP-Clients (auf Ihrer Maschine) — behandeln Sie ihn als Geheimnis; committen Sie ihn nie.

• Der Code ist offen und enthält nicht die Geheimnisse: alle Anmeldeinformationen stammen aus der Umgebung.

API-Konventionen

Geldbeträge in Centavos (Ganzzahl); IDs mit Präfix (sub_, cus_, pay_, ord_…); Daten im Format ISO-8601 UTC. Fehler kommen als Erro <status>: {…}. Den vollständigen Vertrag (OpenAPI 3.1) finden Sie unter GET {RIBBO_API_BASE}/v1/public/schema/.

Entwicklung

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

• Quellcode in src/ (TypeScript ESM). src/index.ts registriert die Tools; src/api.ts ist der HTTP-Client (Bearer).

• Der Build (dist/) wird mit npm run build erzeugt und ist nicht versioniert.

Lizenz

MIT © Ribbo