io.github.dan1d/cobroya
Mercado Pago payments for AI agents: payment links, search, refunds, merchant info.
Ask AI about io.github.dan1d/cobroya
Powered by Claude · Grounded in docs
I know everything about io.github.dan1d/cobroya. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
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:
| Tool | Description |
|---|---|
create_payment_preference | Create a Mercado Pago checkout payment link. Returns an init_point URL to share with buyers. Supports back_urls and notification_url. |
get_payment | Retrieve full details of a payment by ID, including status, amount, and payer info. |
search_payments | Search payments with filters: status (approved, pending, rejected, etc.), sort order, and pagination. |
create_refund | Issue a full or partial refund for a payment. Omit amount for a full refund. |
get_merchant_info | Get the authenticated merchant's profile: user ID, nickname, and site. |
Telegram Bot
CobroYa includes a ready-to-use Telegram bot: @CobroYa_bot
Self-hosting the bot
- Create a bot via @BotFather and get your token.
- Set environment variables:
export MERCADO_PAGO_ACCESS_TOKEN="APP_USR-..."
export TELEGRAM_BOT_TOKEN="your-telegram-bot-token"
- Run:
npx cobroya-telegram
Or from source:
npm run bot
CobroYa supports WhatsApp Business Cloud API for receiving commands and sending payment notifications.
- Create a Meta app at Meta for Developers and enable WhatsApp Business API.
- 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"
- Run the webhook server:
npm run whatsapp
# Starts on http://localhost:3000/webhook
- 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")
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),
);
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
| Variable | Required | Description |
|---|---|---|
MERCADO_PAGO_ACCESS_TOKEN | Yes | Mercado Pago API access token (get one here) |
TELEGRAM_BOT_TOKEN | For Telegram | Telegram bot token from @BotFather |
WHATSAPP_ACCESS_TOKEN | For WhatsApp | Meta Graph API token |
WHATSAPP_PHONE_NUMBER_ID | For WhatsApp | WhatsApp Business phone number ID |
WHATSAPP_VERIFY_TOKEN | For WhatsApp | Webhook verification token |
WA_NOTIFY_PHONE | No | Phone number for WhatsApp payment notifications |
MERCADO_PAGO_WEBHOOK_SECRET | No | HMAC secret for Mercado Pago webhook signature validation |
MP_CURRENCY | No | Default currency (defaults to ARS) |
MP_SUCCESS_URL | No | Default success redirect URL for payment preferences |
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
