mercadopago-claude-marketplace

The official Claude Code plugin marketplace for Mercado Pago payment integrations.

[!WARNING] This project is under active development. APIs, skill structures, and plugin interfaces may change between versions. Use in production integrations at your own discretion. Feedback and contributions are welcome.

---

Overview

A Claude Code plugin that gives you an AI-powered integration assistant for the full Mercado Pago product suite. Ask questions, scaffold projects, review code, and get real-time API guidance — all from your terminal.

• MCP-first architecture — one thin router agent delegates to 4 orchestration skills backed by the live Mercado Pago MCP server
• 4 orchestration skills: mp-integrate, mp-webhooks, mp-test-setup, mp-review
• 7 countries supported: Argentina, Brazil, Mexico, Chile, Colombia, Peru, Uruguay
• Credential leak prevention — hook scans every file write for hardcoded tokens
• OAuth-based auth — connect via /mp-connect, no keychain scripts needed
• 3 slash commands — /mp-integrate, /mp-review, /mp-connect

What's new in v4.1.0

A focused refinement of the v4.0.0 architecture. No breaking changes — same 4 skills, same MCP-first model.

• Bricks gotchas restored: six experiential traps that v4.0.0 lost during the consolidation are back in mp-integrate's Gotchas Bank — ad-blockers blocking sdk.mercadopago.com, debit cards without installments, preferenceId placeholder failures, Status Screen needing payment_id (not order_id), React unmount() in useEffect cleanup, and back_urls same-origin requirement.
• Implementation Report in /mp-review: every review now ends with a structured closure block — Verified / Needs attention / Blockers / Next steps / Scores + Verdict — so developers know if they can ship.
• Orders API push reflected in reviews: mp-review now detects legacy /v1/payments usage and surfaces a forward-looking migration item in Needs attention (not a blocker — existing code works, but the Payments API is being deprecated). Checkout Pro is explicitly exempted since it has no Orders API equivalent.
• Architecture-agnostic CI: validate.yml no longer hardcodes skill filenames. Future refactors that keep the basic plugin structure won't break the build.

Installation

1. Add the marketplace

/plugin marketplace add https://github.com/mercadopago/mercadopago-claude-marketplace.git

2. Install the plugin

/plugin install mercadopago@mercadopago-claude-marketplace

If you are developing this repository locally, you must run bash scripts/install-git-hooks.sh before making commits. This is required to activate the pre-commit hook. The validation command expects claude to be available on the machine.

3. Connect your account

Inside Claude Code, run:

/mp-connect

This starts the OAuth flow. No Access Token or keychain setup required — the MCP server handles authentication via OAuth.

For other IDEs (Cursor, VS Code, Windsurf), add https://mcp.mercadopago.com/mcp via your IDE's MCP settings panel. Run /mp-connect for IDE-specific snippets.

Skills

All product knowledge (endpoint URLs, request/response schemas, code snippets, payment status tables, country availability) is pulled live from the Mercado Pago MCP server. Nothing is hardcoded in the skills.

Commands

Architecture

┌────────────────────────────────────────────────────────┐
│  mp-integration-expert  (router, ~120 lines)           │
│  - MCP-gate every interaction                          │
│  - country detection                                   │
│  - mode detection (Orders API vs legacy)               │
│  - delegates to one of four skills                     │
└──────────────────────────┬─────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┬──────────────────┐
        ▼                  ▼                  ▼                  ▼
   mp-integrate       mp-webhooks       mp-test-setup        mp-review
   (wizard)           (HMAC + MCP        (create_test_user   (quality_checklist
                       webhook tools)     + add_money)        + security floor)
        │                  │                  │                  │
        └──────────────────┴──────────────────┴──────────────────┘
                           │
                           ▼
              ┌───────────────────────────┐
              │  Mercado Pago MCP server  │
              │  (mcp.mercadopago.com)    │
              │                           │
              │  search_documentation     │
              │  quality_checklist        │
              │  quality_evaluation       │
              │  save_webhook             │
              │  simulate_webhook         │
              │  notifications_history…   │
              │  create_test_user         │
              │  add_money_test_user      │
              └───────────────────────────┘

The agent is a thin router (~120 lines) with no embedded product knowledge. Skills translate developer intent into MCP queries and assemble the response. The MCP is the single source of truth — all endpoints, payloads, code snippets, and quality criteria are pulled live. There is no offline mode.

Infrastructure

Requirements

• Claude Code CLI
• Node.js 18+ (for the MCP server)
• Python 3.8+ (for the credential scanning hook)

Contributing

Have a bug to report, a feature to suggest, or a question? Open an issue — that's the best way to contribute. See our Contributing Guidelines for details on how to write a good report or feature request.

Code of Conduct

This project is governed by our Code of Conduct. By participating, you are expected to uphold these standards and help maintain a welcoming and respectful environment for everyone.

Support

You may find technical documentation about Mercado Pago's products and services on the Developer's Website.

Technical Support is available within the Developer's Website Support Section.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

See the LICENSE file for the full license text, and NOTICE for attribution information.

Copyright

Copyright (c) 2026 Mercado Pago (MercadoLibre S.R.L.)