cobroya

CobroYa

使用 Mercado Pago 收款，只需 10 秒。

CobroYa 是一款开源的 Mercado Pago 支付工具，适用于 AI Agent、Telegram、WhatsApp 和自动化平台。可创建支付链接、搜索付款、发起退款——全部通过 AI 助手或聊天机器人完成。

网站 | npm | GitHub

---

快速开始：与 AI 搭配使用

CobroYa 是一个 MCP（Model Context Protocol）服务。只需一步即可将其添加到 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 提供 5 个 MCP 工具，任何已连接的 AI Agent 都可以调用：

工具	说明
create_payment_preference	创建 Mercado Pago 结账支付链接。返回一个可分享给买家的 init_point URL。支持 back_urls 和 notification_url。
get_payment	按 ID 获取付款的完整详情，包括状态、金额和付款人信息。
search_payments	使用筛选条件搜索付款：status（已批准、待处理、已拒绝等）、排序方式和分页。
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 函数调用（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