{
  "markdown": "# CobroYa\n\n**Cobra con Mercado Pago en 10 segundos.**\n\n[![npm version](https://img.shields.io/npm/v/cobroya)](https://www.npmjs.com/package/cobroya)\n[![tests](https://img.shields.io/github/actions/workflow/status/dan1d/mercadopago-tool/ci.yml?label=tests)](https://github.com/dan1d/mercadopago-tool/actions)\n[![coverage](https://img.shields.io/codecov/c/github/dan1d/mercadopago-tool)](https://codecov.io/gh/dan1d/mercadopago-tool)\n[![license](https://img.shields.io/npm/l/cobroya)](./LICENSE)\n\nCobroYa 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.\n\n[Website](https://cobroya.app) | [npm](https://www.npmjs.com/package/cobroya) | [GitHub](https://github.com/dan1d/mercadopago-tool)\n\n---\n\n## Quick Start with AI\n\nCobroYa 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](https://www.mercadopago.com/developers/en/docs/checkout-pro/additional-content/your-integrations/credentials).\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cobroya\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cobroya\"],\n      \"env\": {\n        \"MERCADO_PAGO_ACCESS_TOKEN\": \"APP_USR-...\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add cobroya -- npx -y cobroya \\\n  --env MERCADO_PAGO_ACCESS_TOKEN=APP_USR-...\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"cobroya\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cobroya\"],\n      \"env\": {\n        \"MERCADO_PAGO_ACCESS_TOKEN\": \"APP_USR-...\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to your Windsurf MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"cobroya\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cobroya\"],\n      \"env\": {\n        \"MERCADO_PAGO_ACCESS_TOKEN\": \"APP_USR-...\"\n      }\n    }\n  }\n}\n```\n\n> 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\"*.\n\n---\n\n## Available Tools\n\nCobroYa exposes 5 MCP tools that any connected AI agent can call:\n\n| Tool | Description |\n|------|-------------|\n| `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`. |\n| `get_payment` | Retrieve full details of a payment by ID, including status, amount, and payer info. |\n| `search_payments` | Search payments with filters: `status` (approved, pending, rejected, etc.), sort order, and pagination. |\n| `create_refund` | Issue a full or partial refund for a payment. Omit `amount` for a full refund. |\n| `get_merchant_info` | Get the authenticated merchant's profile: user ID, nickname, and site. |\n\n---\n\n## Telegram Bot\n\nCobroYa includes a ready-to-use Telegram bot: [@CobroYa_bot](https://t.me/CobroYa_bot)\n\n### Self-hosting the bot\n\n1. Create a bot via [@BotFather](https://t.me/BotFather) and get your token.\n2. Set environment variables:\n\n```bash\nexport MERCADO_PAGO_ACCESS_TOKEN=\"APP_USR-...\"\nexport TELEGRAM_BOT_TOKEN=\"your-telegram-bot-token\"\n```\n\n3. Run:\n\n```bash\nnpx cobroya-telegram\n```\n\nOr from source:\n\n```bash\nnpm run bot\n```\n\n---\n\n## WhatsApp\n\nCobroYa supports WhatsApp Business Cloud API for receiving commands and sending payment notifications.\n\n1. Create a Meta app at [Meta for Developers](https://developers.facebook.com/) and enable WhatsApp Business API.\n2. Set environment variables:\n\n```bash\nexport WHATSAPP_ACCESS_TOKEN=\"your-meta-graph-api-token\"\nexport WHATSAPP_PHONE_NUMBER_ID=\"your-phone-number-id\"\nexport WHATSAPP_VERIFY_TOKEN=\"your-webhook-verify-token\"\n```\n\n3. Run the webhook server:\n\n```bash\nnpm run whatsapp\n# Starts on http://localhost:3000/webhook\n```\n\n4. Expose with ngrok (`ngrok http 3000`) and configure the webhook URL in your Meta Dashboard.\n\nFor full details on supported commands and payment notifications, see the [WhatsApp documentation](https://cobroya.app).\n\n---\n\n## Automation Platforms\n\nPre-built packages for popular automation platforms are available in the `packages/` directory:\n\n- **n8n** -- `packages/n8n-nodes-mercadopago`\n- **Zapier** -- `packages/zapier-mercadopago`\n- **Make** -- `packages/make-mercadopago`\n- **Pipedream** -- `packages/pipedream-mercadopago`\n\nEach package wraps the CobroYa core with platform-specific configuration. See the README in each package for setup instructions.\n\n---\n\n## AI Framework Adapters\n\n### LangChain (Python)\n\n```bash\npip install langchain-mercadopago\n```\n\n```python\nfrom langchain_mercadopago import create_mercadopago_tools\n\ntools = create_mercadopago_tools(\"APP_USR-...\")\n\n# Use with any LangChain agent\nfrom langchain.agents import initialize_agent, AgentType\nfrom langchain_openai import ChatOpenAI\n\nagent = initialize_agent(\n    tools=tools,\n    llm=ChatOpenAI(model=\"gpt-4\"),\n    agent=AgentType.OPENAI_FUNCTIONS,\n)\nagent.run(\"Create a payment link for $5000 for a Python course\")\n```\n\n[PyPI](https://pypi.org/project/langchain-mercadopago/)\n\n### OpenAI Function Calling (TypeScript)\n\n```bash\nnpm install openai-mercadopago\n```\n\n```typescript\nimport { createMercadoPagoExecutor } from \"openai-mercadopago\";\n\nconst executor = createMercadoPagoExecutor(process.env.MERCADO_PAGO_ACCESS_TOKEN!);\n\n// Pass executor.definitions to OpenAI's tools parameter\nconst response = await openai.chat.completions.create({\n  model: \"gpt-4\",\n  messages,\n  tools: executor.definitions,\n});\n\n// Execute the tool call\nconst result = await executor.handleToolCall(\n  toolCall.function.name,\n  JSON.parse(toolCall.function.arguments),\n);\n```\n\n[npm](https://www.npmjs.com/package/openai-mercadopago)\n\n---\n\n## Programmatic Usage\n\nInstall as a dependency:\n\n```bash\nnpm install cobroya\n```\n\n```typescript\nimport { createMercadoPagoTools } from \"cobroya\";\n\nconst mp = createMercadoPagoTools(process.env.MERCADO_PAGO_ACCESS_TOKEN!);\n\n// Create a payment link\nconst pref = await mp.tools.create_payment_preference({\n  title: \"Premium Plan\",\n  quantity: 1,\n  currency: \"ARS\",\n  unit_price: 5000,\n});\nconsole.log(pref.init_point); // Checkout URL to share with the buyer\n\n// Search approved payments\nconst payments = await mp.tools.search_payments({ status: \"approved\", limit: 10 });\n\n// Get payment details\nconst payment = await mp.tools.get_payment({ payment_id: \"123456789\" });\n\n// Full refund\nawait mp.tools.create_refund({ payment_id: \"123456789\" });\n\n// Partial refund\nawait mp.tools.create_refund({ payment_id: \"123456789\", amount: 500 });\n\n// Merchant profile\nconst merchant = await mp.tools.get_merchant_info();\n```\n\n### Error Handling\n\n```typescript\nimport { MercadoPagoError } from \"cobroya\";\n\ntry {\n  await mp.tools.get_payment({ payment_id: \"invalid\" });\n} catch (err) {\n  if (err instanceof MercadoPagoError) {\n    console.log(err.status);        // 404\n    console.log(err.isNotFound);     // true\n    console.log(err.isUnauthorized); // false\n    console.log(err.isRateLimited);  // false\n  }\n}\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `MERCADO_PAGO_ACCESS_TOKEN` | Yes | Mercado Pago API access token ([get one here](https://www.mercadopago.com/developers/en/docs/checkout-pro/additional-content/your-integrations/credentials)) |\n| `TELEGRAM_BOT_TOKEN` | For Telegram | Telegram bot token from @BotFather |\n| `WHATSAPP_ACCESS_TOKEN` | For WhatsApp | Meta Graph API token |\n| `WHATSAPP_PHONE_NUMBER_ID` | For WhatsApp | WhatsApp Business phone number ID |\n| `WHATSAPP_VERIFY_TOKEN` | For WhatsApp | Webhook verification token |\n| `WA_NOTIFY_PHONE` | No | Phone number for WhatsApp payment notifications |\n| `MERCADO_PAGO_WEBHOOK_SECRET` | No | HMAC secret for Mercado Pago webhook signature validation |\n| `MP_CURRENCY` | No | Default currency (defaults to `ARS`) |\n| `MP_SUCCESS_URL` | No | Default success redirect URL for payment preferences |\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Watch mode\nnpm run test:watch\n\n# Type-check without emitting\nnpx tsc --noEmit\n\n# Integration test against real Mercado Pago API\nMERCADO_PAGO_ACCESS_TOKEN=APP_USR-... npm run integration\n\n# Start the unified server (Telegram + WhatsApp + webhooks)\nnpm start\n\n# Dev mode with auto-reload\nnpm run dev:server\n\n# Docker\ndocker compose up -d\n```\n\n---\n\n## License\n\n[MIT](./LICENSE) -- by [dan1d](https://dan1d.dev/)\n",
  "bytes": 8595,
  "sha": "42836f6dd3de2b0f7bd6d6a1e0d3c1875661636934b7d7bd7f37f98a2adc3c5d",
  "repo_slug": "dan1d/mercadopago-tool",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dan1d_cobroya_d5c41e62/readme"
}