ribbo-mcp

MCP（Model Context Protocol）サーバー Ribbo。お使いのAIアシスタント（Claude Desktop、Cursor など）を Ribbo の定期課金 API に接続し、それをオペレーターに変えます。AI が実際のアクションを実行できるようになります — サブスクリプションの作成・管理、entitlements の照会、支払いの返金、即時請求、支払い/更新リンクの生成。

認証には、テナントの API key（プレフィックス bk_）を使います。これは 開発者 → API keys のパネルで生成します。このサーバーは公開APIのシンクライアントです。コードにシークレットは一切含まれていません — キーは環境変数で提供します。

要件

• Node.js 18+

• Ribbo の APIキー（bk_…）。参照のみの場合は read スコープのキーを、AI に操作（返金・請求・キャンセルなど）させる場合は write スコープのキーを使います。

Related MCP server: Agent Billy MCP Server

インストール

最も手早い方法 — 何もクローンせずに — は、npx 経由で AIクライアントをパッケージに接続することです。ターミナルで試すには:

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

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

これは stdio で待機します — MCP サーバーはこのように動作します。それと「対話」するのは（後述の）お使いの AIクライアントであり、ターミナではありません。終了するには: Ctrl+C。

設定

環境変数は2つです:

Claude Desktop

claude_desktop_config.json（メニュー → 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"
      }
    }
  }
}

Claude Desktop を再起動します。Ribbo のツールがチャットのツールアイコンに表示されます。

Cursor

.cursor/mcp.json（プロジェクト内）またはグローバル MCP 設定で、上記の同じ mcpServers ブロックを使用します。

npm に公開された後、"github:andrespadeto/ribbo-mcp" を "ribbo-mcp" に置き換えます。

ツール

読み取り（read キーで十分）:

書き込み（write キー必須 — お金/状態を変更）:

セキュリティ

• このキーは テナントを識別し、分離します — 他のテナントのデータには決してアクセスできません。

• 書き込みツールはお金/状態を変更します（返金、請求、キャンセル）。AI が参照のみの場合は read キーを、操作が必要な場合のみ write キーを使用してください。

• キーは MCP クライアントの env（自分のマシン上）にあります — 秘密として取り扱ってください。絶対にコミットしないでください。

• コードはオープンで、シークレットは含まれていません: すべての認証情報は環境から取得されます。

API の規約

金額はセント（整数）; ID はプレフィックス付き（sub_、cus_、pay_、ord_…）; 日付は ISO-8600 UTC。エラーは Erro <status>: {…} の形式で返されます。完全なコントラクト (OpenAPI 3.1) は GET {RIBBO_API_BASE}/v1/public/schema/ にあります。

開発

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

• ソースコードは src/（TypeScript ESM）。src/index.ts がツールを登録し、src/api.ts が HTTP クライアント（Bearer）です。

• ビルド成果物（dist/）は npm run build で生成され、バージョン管理はされません。

ライセンス

MIT © Ribbo