ribbo-mcp

Ribbo의 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Cursor 등의 AI 어시스턴트를 Ribbo의 구독·반복 결제 API에 연결해 어시스턴트를 운영자로 만들어 줍니다. 즉, AI가 실제로 작업을 실행하게 됩니다 — 구독 생성·관리, entitlements 조회, 결제 환불, 즉시 청구, 결제·갱신 링크 생성 등입니다.

인증은 테넌트 API 키(접두사 bk_)로 하며, 대시보드의 개발자 → API keys에서 발급받습니다. 이 서버는 공개 API의 씬 클라이언트(thin client)입니다. 코드에는 어떤 비밀 정보도 들어 있지 않으며, 키만 환경 변수로 넘겨주면 됩니다.

요구 사항

• 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를 누르세요.

설정

환경 변수 두 개를 사용합니다:

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 키 필요 — 자금/상태를 변경하는 작업):

보안

• 이 키는 테넘(tenant)을 식별하고 격리하기 때문에 다른 테넌트의 데이터에는 엑세스할 수 없습니다.

• 쓰기 도구는 금전/상태를 변경합니다 (리펀드, 결제, 취소). AI가 조회만 해야 한다면 read 키를, 그리고 실제 조치가 필요한 곳에서만 write 키를 사용하세요.

• 키는 MCP 클라이언트의 env에 보관되며(클라이언트 기기 위) — 비밀 번호로 취급하고 절대 커밋하지 마세요.

API 규칙

금액은 센트(정수), ID는 sub_, cus_, pay_, ord_… 처럼 접두사가 붙습니다. 날짜는 ISO-8601 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

Wait, the bullet for security: You wrote "보안(신의 기계 위)" but "na sua máquina" -> "자신의 컴퓨터" not "기기". Use "사용자 컴퓨터".

Also, I realised I wrote "이 키는 테넘트(tenant)를 식별하고 격리하기 때문에" - "identary + isolate" -> "식별하고 격리" positive. Use "하기 때문에" maybe extra. Fine.

"3. no code contains secrets" original bullet 4: "O código é aberto e não contém segredos. In my final, I wrote "- O código é elaborately" but I omitted that line? I only wrote 4 bullets? In the final I have 5 bullets? Let's see:

• "이 키는 ..."

• "쓰기 도구..."

• • 키는 MCP 클라이언트의 env에 보안(신의 기계 위) — 비밀 번호로 취급하고 절대 커밋하지 마세요.

• API 규칙: "..." This line is actually a paragraph not bullet? Wait " * API 규칙" in my draft came after bullets? Actually I see in my final text: after "### 계" I wrote " * API 규칙" mistakenly. Let's inspect.

The intended final includes:

보안

• 이 키는 ...

• **쓰기 도구는 ...

• 키는 MCP 클라이언트의 env ... 커밋하지 마세요.

• 코드는 공개이며 시크릿을 포함하지 않습니다 — 모든 인증 정보는 환경 변수에서 제공받습니다.

But in my final, I accidentally inserted " * API 규칙" ?? No, let me look at the draft: after "있다 - 비밀 번호로 취급하고 커밋하지 않는다." Then we had " * API 규칙" because I mis-copied? In the text above:

"* 키는 MCP 클라이언트의 env에 보안(신의 기계 위) — 비밀 번호로 취급하고 절대 커밋하지 마세요.

• API 규칙"

Oops, that is an error. I need to correct: there should be a fourth bullet in security, then a new paragraph "## API 규칙" as heading, not bullet. And I omitted "O código é aberto..." bullet. Need fix.

Let's now rewrite final cleanly.

Also, "비밀 번호" means password; better "비밀 정보" or "기밀로". "비밀로 취급" maybe.

Let's compose final carefully.

Also, "존재하 on env(transformer)" Good.

Let's now use "env" backticks.

We'll include bullet:

• 키는 MCP 클라이언트의 env 환경에 있습니다(사용자의 자신의 컴퓨터). 비밀로 취급하고 절대 커밋하지 마세요.

• 코드는 공개되고 기밀 정보가 포함되어 있지 않습니다. 모들 자격 증명은 환경 변수에서 제공됩니다.

Now, let's ensure no accidental "API rules" markdown.

Now, final answer should be exactly final. I'll output once more.

Need consider whether "Desenvolvedores → API keys" I use "개발자 → API keys". Fine.

Potential minor: "idle" in "API rules" "IDs" and "textbf" etc. Good.

Now, note "A supera" and "2ª via" etc. Good.

Let's# ribbo-mcp

Ribbo의 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Cursor 등의 AI 어시스턴트를 Ribbo의 반복 청구 API에 연결하고, 어시스턴트를 운영자로 만들어 줍니다. AI가 실제 작업을 수행하게 됩니다 — 구독 생성 및 관리, entitlements 조회, 결제 환불, 즉시 청구, 결제·갱신 링크 생성 등입니다.

인증은 테넌트 API key(접두사 bk_)로 하며, 대시보드의 개발자 → API keys에서 발급받습니다. 이 서버는 공개 API의 씬 클라이언트입니다. 코드에 비밀이 저장되지 않습니다 — 사용자가 키를 환경 변수로 제공합니다.

요구사항

• Node.js 18+

• Ribbo API key(bk_…)가 필요합니다. 조회만 하면 read 범위의 키를, AI가 작업(환불, 청구, 취소 등)하게 하려면 write 범위의 키를 사용하세요.

설치

가장 빠른 방법 — 아무것도 클론하지 않고 — 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를 누르세요.

설정

두 가지 환경 변수가 필요합니다:

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-8601 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