io.github.dan1d/cobroya

Official

by dan1d · TypeScript

Mercado Pago payments for AI agents: payment links, search, refunds, merchant info.

Mercado Pago payment integration for AI agents including links, refunds, and merchant info.

README.md8 KBView on GitHub

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:

json

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

Claude Code

bash

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

Cursor

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

json

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

Windsurf

Add to your Windsurf MCP configuration:

json

{
  "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:

bash

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

Run:

bash

npx cobroya-telegram

Or from source:

bash

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:

bash

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:

bash

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)

bash

pip install langchain-mercadopago

python

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)

bash

npm install openai-mercadopago

typescript

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:

bash

npm install cobroya

typescript

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

typescript

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

bash

# 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

Install

Configuration

Environment variables

MERCADO_PAGO_ACCESS_TOKENrequiredsecret

Mercado Pago Access Token (starts with APP_USR-)

claude_desktop_config.json

{
  "mcpServers": {
    "cobroya": {
      "command": "npx",
      "args": [
        "-y",
        "cobroya@1.0.1"
      ],
      "env": {
        "MERCADO_PAGO_ACCESS_TOKEN": "<YOUR_MERCADO_PAGO_ACCESS_TOKEN>"
      }
    }
  }
}