Skip to main content
Glama

mercadopago-mcp

MCP server to inspect Mercado Pago payments, orders, preferences, and webhook signatures from your AI client.

npm version License: MIT TypeScript Read-only by default

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-mcp

The 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-mcp

Check 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

get_payment

Full payment by ID: status, status_detail, amounts, payer, fees, refunds.

search_payments

Filter by status, external_reference, payer_email, and a date range (begin_date/end_date as ISO 8601 or NOW-7DAYS, range picks the date field). Paged with limit (max 100) and offset. Returns compact summaries unless compact: false.

get_merchant_order

Merchant order by ID with items, order_status, paid vs total, and attached payments.

get_preference

Checkout Pro preference by ID: items, back_urls, notification_url, expiration, init_point.

list_payment_methods

Payment methods for the account or a site_id (MLA, MLB, MLM, ...), optionally filtered by payment_type_id.

verify_webhook_signature

Checks an x-signature header locally with HMAC-SHA256. Works offline and without MP_ACCESS_TOKEN.

Write (only with --allow-writes)

Tool

What it does

create_preference

Creates a Checkout Pro preference and returns id and init_point.

refund_payment

Refunds a payment. Requires either amount (partial) or full_refund: true; a call with neither is rejected so a missing amount never means "refund everything".

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: the x-signature header, e.g. ts=1742505638683,v1=0163c3...

  • x_request_id: the x-request-id header

  • data_id: data.id from the notification URL query string, not from the JSON body

  • secret: optional; defaults to MP_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-writes or MP_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_preference must 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

MP_ACCESS_TOKEN

Mercado Pago access token. Required by every tool except verify_webhook_signature.

MP_ALLOW_WRITES

true registers the write tools. Same as --allow-writes.

MP_WEBHOOK_SECRET

Default secret for verify_webhook_signature.

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 --help

Tests 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

MIT © Matías Sánchez González

Available Tools

6 tools
get_merchant_orderGet merchant orderA
Read-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 paymentA
Read-only

Fetch one Mercado Pago payment by ID, including status, status_detail, amounts, payer, fees, and refunds.

Inputs: payment_id (required).

get_preferenceGet preferenceB
Read-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 methodsB
Read-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 paymentsB
Read-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 signatureA
Read-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

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Connects 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.
      5
      34 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      85
      25 npm
      MIT