Cobroya

CobroYa

Cobra con Mercado Pago en 10 segundos.

[npm version] [tests] [coverage] [license]

CobroYa is an open-source Mercado Pago payment tool for AI agents, Telegram, WhatsApp, and automation platforms. Create payment links, search payments, issue refunds -- all from your AI assistant or chat bot.

Website | npm | GitHub

Quick Start with AI

CobroYa is an MCP (Model Context Protocol) server. Add it to your AI tool in one step -- no cloning, no building. Just provide your Mercado Pago access token.

Claude Desktop

Add to your 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

Add to .cursor/mcp.json in your project root:

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

Windsurf

Add to your Windsurf MCP configuration:

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

Once configured, ask your AI assistant things like: "Create a payment link for $5000 for a Python course" or "Show me today's approved payments".

Available Tools

CobroYa exposes 5 MCP tools that any connected AI agent can call:

Telegram Bot

CobroYa includes a ready-to-use Telegram bot: @CobroYa_bot

Self-hosting the bot

1. Create a bot via @BotFather and get your token.
2. Set environment variables:

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

3. Run:

npx cobroya-telegram

Or from source:

npm run bot

WhatsApp

CobroYa supports WhatsApp Business Cloud API for receiving commands and sending payment notifications.

1. Create a Meta app at Meta for Developers and enable WhatsApp Business API.
2. Set environment variables:

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. Run the webhook server:

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

4. Expose with ngrok (ngrok http 3000) and configure the webhook URL in your Meta Dashboard.

For full details on supported commands and payment notifications, see the WhatsApp documentation.

Automation Platforms

Pre-built packages for popular automation platforms are available in the packages/ directory:

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

Each package wraps the CobroYa core with platform-specific configuration. See the README in each package for setup instructions.

AI Framework Adapters

LangChain (Python)

pip install langchain-mercadopago

from langchain_mercadopago import create_mercadopago_tools
tools = create_mercadopago_tools("APP_USR-...")
# Use with any LangChain agentfrom langchain.agents import initialize_agent, AgentTypefrom 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 parameterconst response = await openai.chat.completions.create({  model: "gpt-4",  messages,  tools: executor.definitions,});
// Execute the tool callconst result = await executor.handleToolCall(  toolCall.function.name,  JSON.parse(toolCall.function.arguments),);

npm

Programmatic Usage

Install as a dependency:

npm install cobroya

import { createMercadoPagoTools } from "cobroya";
const mp = createMercadoPagoTools(process.env.MERCADO_PAGO_ACCESS_TOKEN!);
// Create a payment linkconst 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 paymentsconst payments = await mp.tools.search_payments({ status: "approved", limit: 10 });
// Get payment detailsconst payment = await mp.tools.get_payment({ payment_id: "123456789" });
// Full refundawait mp.tools.create_refund({ payment_id: "123456789" });
// Partial refundawait mp.tools.create_refund({ payment_id: "123456789", amount: 500 });
// Merchant profileconst merchant = await mp.tools.get_merchant_info();

Error Handling

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

Environment Variables

Development

# Install dependenciesnpm install
# Buildnpm run build
# Run all testsnpm test
# Run tests with coveragenpm run test:coverage
# Watch modenpm run test:watch
# Type-check without emittingnpx tsc --noEmit
# Integration test against real Mercado Pago APIMERCADO_PAGO_ACCESS_TOKEN=APP_USR-... npm run integration
# Start the unified server (Telegram + WhatsApp + webhooks)npm start
# Dev mode with auto-reloadnpm run dev:server
# Dockerdocker compose up -d

License

MIT -- by dan1d