Cobroya

CobroYa

Cobra con Mercado Pago en 10 segundos.

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"

1. 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"

1. Run the webhook server:

npm run whatsapp

Starts on http://localhost:3000/webhook

1. 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 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

---

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 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();

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

---

License

MIT -- by dan1d