cobroya

CobroYa

Mercado Pago で 10 秒で代金を回収。

CobroYa は、AI エージェント、Telegram、WhatsApp、自動化プラットフォーム向けのオープンソース Mercado Pago 決済ツールです。決済リンクの作成、支払いの検索、返金の発行を、AI アシスタントやチャットボットから実行できます。

ウェブサイト | npm | GitHub

---

AI ですぐに始める

CobroYa は MCP（Model Context Protocol）サーバーです。クローンやビルドは不要で、1 ステップで AI ツールに追加できます。Mercado Pago アクセストークンを指定するだけです。

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "cobroya": {
      "command": "npx",
      "args": ["-y", "cobroya"],
      "env": {
        "MERCADO_PAGO_ACCESS_TOKEN": "APP_USR-..."
      }
    }
  }
}

Claude Code

claude mcp add cobroya -- npx -y cobroya \
  --env MERCADO_PAGO_ACCESS_TOKEN=APP_USR-...

Cursor

プロジェクトのルートにある .cursor/mcp.json に追加します：

{
  "mcpServers": {
    "cobroya": {
      "command": "npx",
      "args": ["-y", "cobroya"],
      "env": {
        "MERCADO_PAGO_ACCESS_TOKEN": "APP_USR-..."
      }
    }
  }
}

Windsurf

Windsurf の MCP 設定に追加します：

{
  "mcpServers": {
    "cobroya": {
      "command": "npx",
      "args": ["-y", "cobroya"],
      "env": {
        "MERCADO_PAGO_ACCESS_TOKEN": "APP_USR-..."
      }
    }
  }
}

設定が完了したら、AI アシスタントに「Python コースの 5000 ドルの決済リンクを作成して」や「今日承認された支払いを表示して」のように依頼できます。

---

利用可能なツール

CobroYa は、接続した AI エージェントが呼び出せる 5 つの MCP ツールを提供します：

ツール	説明
create_payment_preference	Mercado Pago のチェックアウト用決済リンクを作成します。購入者と共有する init_point URL を返します。back_urls と notification_url に対応しています。
get_payment	ID を指定して、ステータス、金額、支払者情報など、支払いの詳細を取得します。
search_payments	status（approved、pending、rejected など）、並べ替え順、ページネーションによるフィルターを使って支払いを検索します。
create_refund	支払いの全額または一部を返金します。全額返金する場合は amount を省略します。
get_merchant_info	認証済み加盟店のプロフィール（ユーザー ID、ニックネーム、サイト）を取得します。

---

Telegram ボット

CobroYa には、すぐに使える Telegram ボットが含まれています：CobroYa_bot

ボットのセルフホスト

1. @BotFather からボットを作成し、トークンを取得します。
2. 環境変数を設定します：

export MERCADO_PAGO_ACCESS_TOKEN="APP_USR-..."
export TELEGRAM_BOT_TOKEN="your-telegram-bot-token"

3. 実行します：

npx cobroya-telegram

または、ソースから実行します：

npm run bot

---

WhatsApp

CobroYa は、コマンドの受信と決済通知の送信に WhatsApp Business Cloud API をサポートしています。

1. Meta for Developers で Meta アプリを作成し、WhatsApp Business API を有効にします。
2. 環境変数を設定します：

export WHATSAPP_ACCESS_TOKEN="your-meta-graph-api-token"
export WHATSAPP_PHONE_NUMBER_ID="your-phone-number-id"
export WHATSAPP_VERIFY_TOKEN="your-webhook-verify-token"

3. Webhook サーバーを実行します：

npm run whatsapp
# Starts on http://localhost:3000/webhook

4. ngrok（ngrok http 3000）で公開し、Meta Dashboard で Webhook URL を設定します。

対応コマンドと決済通知の詳細については、WhatsApp ドキュメントを参照してください。

---

自動化プラットフォーム

人気の自動化プラットフォーム向けの事前構築済みパッケージは、packages/ ディレクトリで利用できます：

• n8n -- packages/n8n-nodes-mercadopago
• Zapier -- packages/zapier-mercadopago
• Make -- packages/make-mercadopago
• Pipedream -- packages/pipedream-mercadopago

各パッケージは、CobroYa のコア機能をプラットフォーム固有の設定でラップしています。セットアップ手順については、各パッケージの README を参照してください。

---

AI フレームワークアダプター

LangChain（Python）

pip install langchain-mercadopago

from langchain_mercadopago import create_mercadopago_tools

tools = create_mercadopago_tools("APP_USR-...")

# Use with any LangChain agent
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

agent = initialize_agent(
    tools=tools,
    llm=ChatOpenAI(model="gpt-4"),
    agent=AgentType.OPENAI_FUNCTIONS,
)
agent.run("Create a payment link for $5000 for a Python course")

PyPI

OpenAI Function Calling（TypeScript）

npm install openai-mercadopago

import { createMercadoPagoExecutor } from "openai-mercadopago";

const executor = createMercadoPagoExecutor(process.env.MERCADO_PAGO_ACCESS_TOKEN!);

// Pass executor.definitions to OpenAI's tools parameter
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages,
  tools: executor.definitions,
});

// Execute the tool call
const result = await executor.handleToolCall(
  toolCall.function.name,
  JSON.parse(toolCall.function.arguments),
);

npm

---

プログラムからの使用

依存関係としてインストールします：

npm install cobroya

import { createMercadoPagoTools } from "cobroya";

const mp = createMercadoPagoTools(process.env.MERCADO_PAGO_ACCESS_TOKEN!);

// Create a payment link
const pref = await mp.tools.create_payment_preference({
  title: "Premium Plan",
  quantity: 1,
  currency: "ARS",
  unit_price: 5000,
});
console.log(pref.init_point); // Checkout URL to share with the buyer

// Search approved payments
const payments = await mp.tools.search_payments({ status: "approved", limit: 10 });

// Get payment details
const payment = await mp.tools.get_payment({ payment_id: "123456789" });

// Full refund
await mp.tools.create_refund({ payment_id: "123456789" });

// Partial refund
await mp.tools.create_refund({ payment_id: "123456789", amount: 500 });

// Merchant profile
const merchant = await mp.tools.get_merchant_info();

エラー処理

import { MercadoPagoError } from "cobroya";

try {
  await mp.tools.get_payment({ payment_id: "invalid" });
} catch (err) {
  if (err instanceof MercadoPagoError) {
    console.log(err.status);        // 404
    console.log(err.isNotFound);     // true
    console.log(err.isUnauthorized); // false
    console.log(err.isRateLimited);  // false
  }
}

---

環境変数

変数	必須	説明
MERCADO_PAGO_ACCESS_TOKEN	はい	Mercado Pago API アクセストークン（こちらから取得）
TELEGRAM_BOT_TOKEN	Telegram 用	@BotFather から取得した Telegram ボットトークン
WHATSAPP_ACCESS_TOKEN	WhatsApp 用	Meta Graph API トークン
WHATSAPP_PHONE_NUMBER_ID	WhatsApp 用	WhatsApp Business の電話番号 ID
WHATSAPP_VERIFY_TOKEN	WhatsApp 用	Webhook 検証トークン
WA_NOTIFY_PHONE	いいえ	WhatsApp の決済通知に使用する電話番号
MERCADO_PAGO_WEBHOOK_SECRET	いいえ	Mercado Pago の webhook 署名検証用 HMAC シークレット
MP_CURRENCY	いいえ	デフォルトの通貨（既定値は ARS）
MP_SUCCESS_URL	いいえ	決済設定のデフォルトの成功時リダイレクト URL

---

開発

# Install dependencies
npm install

# Build
npm run build

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

# Type-check without emitting
npx tsc --noEmit

# Integration test against real Mercado Pago API
MERCADO_PAGO_ACCESS_TOKEN=APP_USR-... npm run integration

# Start the unified server (Telegram + WhatsApp + webhooks)
npm start

# Dev mode with auto-reload
npm run dev:server

# Docker
docker compose up -d

---

ライセンス

MIT -- dan1d による