mercadopago-mcp
Provides tools to inspect Mercado Pago payments, merchant orders, Checkout Pro preferences, and payment methods, and to verify webhook signatures. With writes enabled, it can also create Checkout Pro preferences and refund payments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mercadopago-mcp Why was payment 1234567890 rejected? Show me the status detail."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mercadopago-mcp
MCP server to inspect Mercado Pago payments, orders, preferences, and webhook signatures from your AI client.
Ask your assistant why a payment was rejected, what a merchant order contains, or whether a webhook signature is valid, without leaving the editor. Write tools (create a preference, refund a payment) only exist when you start the server with --allow-writes.
Built from running Mercado Pago in production for a web and Android marketplace, where most of the debugging time went into payment lookups, order reconciliation, and webhook signatures.
Quick start
MP_ACCESS_TOKEN=APP_USR-your-token npx -y mercadopago-mcpThe server speaks MCP over stdio, so you normally let your client start it with one of the configs below. Run npx -y mercadopago-mcp --help to see all options.
Related MCP server: Alternative Payments MCP Server
Requirements
Node.js 20 or newer
A Mercado Pago access token (
APP_USR-...for production, or a test user's token). Get it from Your integrations > your app > Production credentials or Test credentials.
Setup
The server runs over stdio through npx. Every client config below passes the token through env; it never needs to be in a file inside your repo.
Claude Desktop
Edit claude_desktop_config.json (Settings > Developer > Edit Config):
{
"mcpServers": {
"mercadopago": {
"command": "npx",
"args": ["-y", "mercadopago-mcp"],
"env": {
"MP_ACCESS_TOKEN": "APP_USR-your-token",
"MP_WEBHOOK_SECRET": "your-webhook-secret"
}
}
}
}Restart Claude Desktop after saving.
Cursor
Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"mercadopago": {
"command": "npx",
"args": ["-y", "mercadopago-mcp"],
"env": {
"MP_ACCESS_TOKEN": "APP_USR-your-token"
}
}
}
}Claude Code
claude mcp add mercadopago --scope user \
-e MP_ACCESS_TOKEN=APP_USR-your-token \
-e MP_WEBHOOK_SECRET=your-webhook-secret \
-- npx -y mercadopago-mcpCheck it with claude mcp list. To share the server with a team, commit a project-scoped .mcp.json instead and keep the token in each developer's shell environment:
{
"mcpServers": {
"mercadopago": {
"command": "npx",
"args": ["-y", "mercadopago-mcp"],
"env": {
"MP_ACCESS_TOKEN": "${MP_ACCESS_TOKEN}"
}
}
}
}Enabling write tools
Add --allow-writes to the args, or set MP_ALLOW_WRITES=true in env:
"args": ["-y", "mercadopago-mcp", "--allow-writes"]Use a test user's token while you try this out.
Tools
Read-only (always registered)
Tool | What it does |
| Full payment by ID: status, |
| Filter by |
| Merchant order by ID with items, |
| Checkout Pro preference by ID: items, |
| Payment methods for the account or a |
| Checks an |
Write (only with --allow-writes)
Tool | What it does |
| Creates a Checkout Pro preference and returns |
| Refunds a payment. Requires either |
Both write tools accept an optional idempotency_key. Reuse it when retrying so Mercado Pago does not apply the operation twice. Without it, every call gets a fresh key.
Verifying webhooks
Pass the raw values from the incoming request:
x_signature: thex-signatureheader, e.g.ts=1742505638683,v1=0163c3...x_request_id: thex-request-idheaderdata_id:data.idfrom the notification URL query string, not from the JSON bodysecret: optional; defaults toMP_WEBHOOK_SECRET. Prefer the env var so the secret stays out of the chat.max_age_seconds: optional replay window. Leave it out when checking old notifications.
The result includes valid, a reason, and the exact manifest that was signed (id:<data.id>;request-id:<x-request-id>;ts:<ts>;). When a signature fails, compare that manifest with what your backend builds: the usual causes are reading data.id from the body instead of the query string, or not lowercasing alphanumeric IDs.
Example prompts
"Why was payment 1234567890 rejected?"
"List approved payments from the last 7 days for external_reference order-981."
"Merchant order 987654321 says paid but my order is pending. What payments does it have?"
"Verify this webhook: x-signature
ts=...,v1=..., x-request-id..., data.id...."
Security model
Read-only by default. Write tools are not registered, so the model cannot call them, unless you pass
--allow-writesorMP_ALLOW_WRITES=true.Token loaded lazily. The server starts without
MP_ACCESS_TOKEN; API-backed tools return a clear error until it is set.--help,--version, and webhook verification never need it.No secrets in output. The access token is stripped from any error text returned by the API, and webhook results never echo the secret.
Validated inputs. Every tool argument is checked with zod before any request is made. IDs are path-encoded, and URLs passed to
create_preferencemust be HTTPS.Stdout is protocol-only. Diagnostics go to stderr, so nothing corrupts the JSON-RPC stream.
15 second timeout on every API call.
Use a token with the smallest scope that covers what you need, and a test user's token for anything involving writes.
Environment variables
Variable | Purpose |
| Mercado Pago access token. Required by every tool except |
|
|
| Default secret for |
Development
git clone https://github.com/DevModee/mercadopago-mcp.git
cd mercadopago-mcp
npm install
npm run typecheck
npm run build
npm test
node dist/index.js --helpTests use node --test with a mocked fetch; they never call the real API.
To try a local build in a client, point command at node and args at the absolute path of dist/index.js.
License
Available Tools
6 toolsget_merchant_orderGet merchant orderARead-only
Fetch a merchant order by ID: order_status, total vs paid amount, items, and every payment attached to it. Useful when a webhook arrives with topic=merchant_order.
Inputs: merchant_order_id (required).
get_paymentGet paymentARead-only
Fetch one Mercado Pago payment by ID, including status, status_detail, amounts, payer, fees, and refunds.
Inputs: payment_id (required).
get_preferenceGet preferenceBRead-only
Fetch a Checkout Pro preference by ID: items, back_urls, notification_url, external_reference, expiration, and init_point.
Inputs: preference_id (required).
list_payment_methodsList payment methodsBRead-only
List payment methods available to the account or to a country site, optionally filtered by payment type.
Inputs: compact, site_id, payment_type_id, include_inactive.
search_paymentsSearch paymentsBRead-only
Search payments on the account by status, external_reference, payer email, and date range. Returns paging info and compact summaries unless compact=false.
Inputs: sort, limit, range, offset, +7 more.
verify_webhook_signatureVerify webhook signatureARead-only
Verify a Mercado Pago webhook x-signature locally with HMAC-SHA256. Runs offline and needs no access token. Returns whether it is valid and the signed manifest for debugging.
Inputs: x_signature (required), secret, data_id, x_request_id, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct resource or action: single payment, merchant order, payment search, Checkout Pro preference, payment method catalog, and offline webhook signature verification. The two 'get_*' tools differ clearly by resource (payment vs merchant_order vs preference), and verify_webhook_signature is unmistakable. No two tools compete for the same request.
All names follow a clean snake_case verb_noun pattern: get_payment, get_merchant_order, search_payments, get_preference, list_payment_methods, verify_webhook_signature. Plural/singular usage matches whether the operation is a list/search versus a single fetch.
Six tools is a tight, well-scoped surface for a payments/checkout integration, with each tool earning its place. It leans slightly thin given the breadth of the Mercado Pago domain, but nothing is redundant.
The surface is read-only: it can fetch and search payments and orders and verify webhooks, but there is no create_payment, create_preference, refund_payment, or cancel operation, so agents cannot complete write-side workflows. Refund data is only visible indirectly through get_payment. These are notable gaps for a payment integration rather than minor ones.
Maintenance
Related MCP Connectors
Payment identity intelligence for AI agents.
Analyzes delegated AI payment authority and exposes supported Stripe/x402 evidence contracts.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Connect AI to store orders, products and inventory with scoped access and human approvals.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects AI agents to Mercado Pago, the leading payment platform in Latin America. Create payment links, search payments, get payment details, issue refunds, and retrieve merchant info.534 npm3MIT

Alternative Payments MCPofficial
AlicenseNot gradedqualityBmaintenanceProvides AI assistants with read and safe-write access to Alternative Payments customers, invoices, payment requests, transactions, payouts, and webhooks without directly moving money.Apache 2.0- FlicenseNot gradedqualityBmaintenanceEnables secure, bilingual AI assistants to query and manage payments, orders, refunds, transactions, wallets, fraud risk, and statistics with per-user data isolation enforced on every tool call.-

Pletopay MCP Serverofficial
AlicenseBqualityCmaintenanceEnables AI agents to manage payments, virtual accounts, customers, transfers, refunds, settlements, checkout, payment links, invoices, subscriptions, reports, webhooks, and sandbox operations through the API, with built-in safeguards for live money movement.8525 npmMIT