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:

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):

Writing (requires a write key — moves money/state):

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