Skip to main content
Glama
Mercado Pago MCP Server

Mercado Pago MCP Server

by hdbookie

Mercado Pago MCP Server

A comprehensive Model Context Protocol (MCP) server for Mercado Pago API integration. This server provides 27+ tools for payment processing, PIX payments with QR codes, fraud detection, analytics, accounting exports, and much more - making any AI capable of handling complete payment operations.

🚀 Quick Install

Simply use npx to run the server directly in your Claude Desktop configuration:

{
  "mcpServers": {
    "mercado-pago": {
      "command": "npx",
      "args": ["mercado-pago-mcp"],
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
        "MERCADOPAGO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Option 2: Global Install

npm install -g mercado-pago-mcp

Then in Claude Desktop config:

{
  "mcpServers": {
    "mercado-pago": {
      "command": "mercado-pago-mcp",
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
        "MERCADOPAGO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Option 3: Local Install

git clone https://github.com/hdbookie/mercado-pago-mcp.git
cd mercado-pago-mcp
npm install
npm run build

Then in Claude Desktop config:

{
  "mcpServers": {
    "mercado-pago": {
      "command": "node",
      "args": ["/path/to/mercado-pago-mcp/dist/index.js"],
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
        "MERCADOPAGO_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Related MCP server: mercadolibre-mcp

Features

🎯 Core Capabilities (v1.0)

  • Payment Operations

    • Create payments

    • Get payment details

    • Search payments with filters

    • Cancel pending payments

  • Refund Processing

    • Full refunds

    • Partial refunds

  • Customer Management

    • Create customers

    • Get customer details

    • Search customers

  • Payment Links

    • Create checkout preferences

    • Generate payment links with custom URLs

    • Set expiration dates

🚀 Advanced Features (v2.0)

  • PIX Payments

    • Create PIX payments with QR codes

    • Generate copy-paste PIX codes

    • Set custom expiration times

  • Subscription Management

    • Create recurring subscriptions

    • Update/pause/cancel subscriptions

    • Manage subscription frequencies

  • Marketplace & Split Payments

    • Split payments between multiple sellers

    • Configure platform fees

    • Manage disbursements

  • Card Management

    • Save cards for future use

    • List customer's saved cards

    • Tokenized card payments

  • Batch Processing

    • Create multiple payments in bulk

    • Batch status updates

    • Bulk refund processing

  • Reports & Analytics

    • Generate payment reports

    • Export data in multiple formats

    • Date range filtering

💼 Business Features (v3.0)

  • Real-time Monitoring

    • Monitor payment status changes

    • Configurable check intervals

    • Status change notifications

  • Fraud Detection

    • Risk scoring system

    • Pattern analysis

    • Fraud indicators and recommendations

  • Analytics Dashboard

    • Revenue metrics and KPIs

    • Payment method breakdowns

    • Customer insights and trends

  • Accounting Integration

    • Export to QuickBooks format

    • Export to Xero format

    • Export to Sage format

    • CSV export for custom systems

  • Tax Calculations

    • Brazilian tax calculations (ICMS, PIS, COFINS, ISS)

    • Regional tax rates by state

    • Product type tax differentiation

  • Payment Automation

    • Automatic retry for failed payments

    • Payment reminder scheduling

    • Smart retry strategies

  • Testing Tools

    • Webhook simulation

    • Sandbox/Production environment support

⚙️ Configuration

Step 1: Get Mercado Pago Credentials

  1. Go to Mercado Pago Developers

  2. Create an application

  3. Get your Access Token:

    • For Testing: Use the TEST token (starts with TEST-)

    • For Production: Use the PRODUCTION token (starts with APP_USR-)

Step 2: Configure Claude Desktop

Open your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Add the configuration from the Quick Install section above.

Step 3: Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

🔐 Environment Configuration

{
  "MERCADOPAGO_ACCESS_TOKEN": "TEST-your-sandbox-token",
  "MERCADOPAGO_ENVIRONMENT": "sandbox"
}

Production

{
  "MERCADOPAGO_ACCESS_TOKEN": "APP_USR-your-production-token",
  "MERCADOPAGO_ENVIRONMENT": "production"
}

Running Both Environments

You can run both staging and production simultaneously:

{
  "mcpServers": {
    "mercado-pago-sandbox": {
      "command": "npx",
      "args": ["mercado-pago-mcp"],
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "TEST-your-sandbox-token",
        "MERCADOPAGO_ENVIRONMENT": "sandbox"
      }
    },
    "mercado-pago-production": {
      "command": "npx",
      "args": ["mercado-pago-mcp"],
      "env": {
        "MERCADOPAGO_ACCESS_TOKEN": "APP_USR-your-production-token",
        "MERCADOPAGO_ENVIRONMENT": "production"
      }
    }
  }
}

Available Tools (27+ Total)

Core Payment Tools

create_payment

Create a new payment in Mercado Pago.

Parameters:

  • amount (number, required): Payment amount

  • description (string, required): Payment description

  • payerEmail (string, required): Payer's email address

  • paymentMethodId (string, required): Payment method (e.g., 'pix', 'credit_card')

  • installments (number, optional): Number of installments for credit card

Example:

{
  "amount": 100.50,
  "description": "Product purchase",
  "payerEmail": "customer@example.com",
  "paymentMethodId": "pix"
}

get_payment

Get detailed information about a specific payment.

Parameters:

  • paymentId (string, required): The payment ID to retrieve

search_payments

Search for payments with various filters.

Parameters:

  • status (string, optional): Payment status (approved, pending, rejected)

  • dateFrom (string, optional): Start date in ISO format

  • dateTo (string, optional): End date in ISO format

  • payerEmail (string, optional): Filter by payer email

  • limit (number, optional): Maximum results (default: 10)

cancel_payment

Cancel a pending payment.

Parameters:

  • paymentId (string, required): Payment ID to cancel

create_refund

Create a full or partial refund for a payment.

Parameters:

  • paymentId (string, required): Payment ID to refund

  • amount (number, optional): Amount to refund (omit for full refund)

create_customer

Create a new customer profile.

Parameters:

  • email (string, required): Customer email

  • firstName (string, optional): First name

  • lastName (string, optional): Last name

  • phone (string, optional): Phone number

  • identificationType (string, optional): ID type (CPF, CNPJ, etc.)

  • identificationNumber (string, optional): ID number

get_customer

Get customer details by ID.

Parameters:

  • customerId (string, required): Customer ID

search_customers

Search for customers.

Parameters:

  • email (string, optional): Filter by email

  • limit (number, optional): Maximum results (default: 10)

Create a payment link (checkout preference).

Parameters:

  • title (string, required): Product/service title

  • amount (number, required): Price

  • quantity (number, optional): Quantity (default: 1)

  • expirationDate (string, optional): Expiration date in ISO format

  • successUrl (string, optional): Redirect URL after success

  • failureUrl (string, optional): Redirect URL after failure

  • pendingUrl (string, optional): Redirect URL for pending

Example:

{
  "title": "Premium Subscription",
  "amount": 29.99,
  "quantity": 1,
  "successUrl": "https://mysite.com/success",
  "failureUrl": "https://mysite.com/failure"
}

simulate_webhook

Simulate webhook notifications for testing.

Parameters:

  • type (string, required): Webhook type

    • payment.created

    • payment.updated

    • payment.approved

    • payment.rejected

  • paymentId (string, required): Payment ID for the webhook

Advanced Payment Tools (v2.0+)

create_pix_payment

Create a PIX payment with QR code and copy-paste code.

Parameters:

  • amount (number, required): Payment amount

  • description (string, required): Payment description

  • payerEmail (string, required): Payer's email

  • expirationMinutes (number, optional): Minutes until expiration

create_subscription

Create a recurring subscription.

Parameters:

  • title (string, required): Subscription title

  • amount (number, required): Recurring amount

  • frequency (number, required): Billing frequency

  • frequencyType (string, required): 'days', 'months', or 'years'

  • payerEmail (string, required): Subscriber's email

create_split_payment

Create marketplace split payments between multiple sellers.

Parameters:

  • amount (number, required): Total amount

  • splits (array, required): Array of split configurations with collectorId, amount, and fee

batch_create_payments

Create multiple payments in a single batch operation.

Parameters:

  • payments (array, required): Array of payment objects

  • processInParallel (boolean, optional): Process payments in parallel

Business Intelligence Tools (v3.0+)

get_analytics_dashboard

Get comprehensive payment analytics and insights.

Parameters:

  • period (string, optional): 'day', 'week', 'month', 'quarter', 'year'

  • metrics (array, optional): Specific metrics to include

detect_fraud_risk

Analyze a payment for fraud risk indicators.

Parameters:

  • paymentId (string, required): Payment ID to analyze

  • includeRecommendations (boolean, optional): Include action recommendations

monitor_payment_status

Monitor a payment for status changes in real-time.

Parameters:

  • paymentId (string, required): Payment ID to monitor

  • intervalSeconds (number, optional): Check interval

  • maxChecks (number, optional): Maximum number of checks

export_to_accounting

Export payment data to accounting software formats.

Parameters:

  • format (string, required): 'quickbooks', 'xero', 'sage', or 'csv'

  • dateFrom (string, required): Start date

  • dateTo (string, required): End date

  • includeRefunds (boolean, optional): Include refunded payments

calculate_taxes

Calculate Brazilian taxes for payments.

Parameters:

  • amount (number, required): Base amount

  • region (string, required): Brazilian state code

  • productType (string, optional): 'physical', 'digital', or 'service'

schedule_payment_reminder

Schedule payment reminders for customers.

Parameters:

  • customerId (string, required): Customer ID

  • amount (number, required): Payment amount

  • dueDate (string, required): Due date

  • reminderSchedule (array, optional): Days before due date to send reminders

retry_failed_payment

Automatically retry a failed payment with smart strategies.

Parameters:

  • originalPaymentId (string, required): Failed payment ID

  • updateAmount (boolean, optional): Allow amount adjustment

  • useAlternativeMethod (boolean, optional): Try alternative payment methods

Usage Examples

With Claude Desktop

Once configured, you can use natural language to interact with Mercado Pago:

"Create a payment for $50 for john@example.com using PIX"

"Search for all approved payments from the last week"

"Create a refund for payment ID 12345678"

"Generate a payment link for a $99 product that expires in 24 hours"

Direct API Usage

// Example: Create a payment
const payment = await createPayment({
  amount: 100.00,
  description: "Test payment",
  payerEmail: "test@example.com",
  paymentMethodId: "pix"
});

// Example: Process a refund
const refund = await createRefund({
  paymentId: "12345678",
  amount: 50.00  // Partial refund
});

Development

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Debug mode
npm run inspect

Testing

The server includes sandbox support for safe testing:

  1. Use sandbox Access Token

  2. Set MERCADOPAGO_ENVIRONMENT=sandbox

  3. Use test credit cards provided by Mercado Pago

  4. Simulate webhooks with the simulate_webhook tool

Test Credit Cards (Sandbox)

  • Approved: 5031 4332 1540 6351

  • Pending: 5031 4332 1540 6351

  • Rejected: 5031 4332 1540 6351

Security Considerations

  • Never commit your Access Token to version control

  • Use environment variables for sensitive data

  • Use sandbox environment for development

  • Implement proper error handling in production

  • Consider rate limiting for production deployments

Webhook Integration

For production use, set up webhooks in your Mercado Pago dashboard:

  1. Go to Your Application > Webhooks

  2. Add your webhook URL

  3. Select events to receive

  4. Use the simulate_webhook tool for testing

Troubleshooting

Common Issues

"Invalid Access Token"

  • Verify your token is correct

  • Check if using sandbox vs production token

  • Ensure token has necessary permissions

"Payment method not available"

  • Check if payment method is enabled in your account

  • Verify country/region support

"Customer already exists"

  • Use search_customers to find existing customer

  • Update existing customer instead of creating new

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues and questions:

  • Open an issue on GitHub

  • Check Mercado Pago documentation

  • Contact Mercado Pago support for API-specific issues

Roadmap

✅ Completed (v2.0 - v3.0)

  • PIX payments with QR codes

  • Subscription management

  • Marketplace/split payments

  • Saved cards management

  • Batch payment processing

  • Advanced reporting and analytics

  • Fraud detection system

  • Payment status monitoring

  • Accounting software exports (QuickBooks, Xero, Sage)

  • Brazilian tax calculations

  • Payment retry automation

  • Payment reminder scheduling

🚧 Planned Features

  • Multi-language support (Portuguese, Spanish, English)

  • Rate limiting and caching optimization

  • Boleto bancário support

  • Advanced webhook management

  • Payment dispute handling

  • Multi-currency conversion

  • A/B testing for payment methods

  • Machine learning fraud detection


Built with ❤️ for the developer community

Available Tools

27 tools
batch_create_paymentsC

Create multiple payments in batch

Inputs: payments (required).

calculate_taxesA

Calculate taxes for a payment based on region

Inputs: amount (required), region (required), productType.

cancel_paymentB

Cancel a pending payment

Inputs: paymentId (required).

create_customerB

Create a new customer

Inputs: email (required), phone, lastName, firstName, +2 more.

create_paymentC

Create a new payment in Mercado Pago

Inputs: amount (required), payerEmail (required), description (required), paymentMethodId (required), +1 more.

create_pix_paymentB

Create a PIX payment with QR code

Inputs: amount (required), payerEmail (required), description (required), payerDocument, +3 more.

create_refundC

Create a refund for a payment

Inputs: paymentId (required), amount.

create_split_paymentC

Create a marketplace split payment

Inputs: amount (required), splits (required), payerEmail (required), description (required), +1 more.

create_subscriptionC

Create a recurring subscription

Inputs: title (required), amount (required), frequency (required), payerEmail (required), +3 more.

detect_fraud_riskB

Analyze payment for fraud risk indicators

Inputs: paymentId (required), includeRecommendations.

export_to_accountingB

Export payment data to accounting software format

Inputs: dateTo (required), format (required), dateFrom (required), includeRefunds.

generate_reportsC

Generate payment reports

Inputs: dateTo (required), dateFrom (required), reportType (required), format.

get_analytics_dashboardC

Get comprehensive payment analytics and metrics

Inputs: period, metrics.

get_customerB

Get customer details

Inputs: customerId (required).

get_paymentC

Get payment details by ID

Inputs: paymentId (required).

get_payment_methodsA

Get available payment methods for your country

Inputs: no named parameters.

get_subscriptionC

Get subscription details

Inputs: subscriptionId (required).

list_saved_cardsC

List customer's saved cards

Inputs: customerId (required).

monitor_payment_statusC

Monitor payment status changes in real-time

Inputs: paymentId (required), webhookUrl, checkInterval.

retry_failed_paymentC

Automatically retry a failed payment with smart logic

Inputs: paymentId (required), maxRetries, retryStrategy.

save_cardB

Save a card for future payments

Inputs: cardNumber (required), customerId (required), securityCode (required), cardholderName (required), +2 more.

schedule_payment_reminderC

Schedule automatic payment reminders

Inputs: amount (required), dueDate (required), customerId (required), reminderSchedule.

search_customersC

Search for customers

Inputs: email, limit.

search_paymentsC

Search for payments with filters

Inputs: limit, dateTo, status, dateFrom, +1 more.

simulate_webhookA

Simulate a webhook notification for testing

Inputs: type (required), paymentId (required).

update_subscriptionB

Update subscription (pause, resume, modify)

Inputs: subscriptionId (required), amount, status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools target distinct resource-action pairs, but there is some potential confusion between general payment creation (create_payment) and specific variants (create_pix_payment, create_split_payment, batch_create_payments) as well as among reporting/analytics tools. Descriptions mitigate most ambiguity.

    Naming Consistency4/5

    All tools use snake_case and mostly follow a verb_noun pattern, but a few names deviate from the standard (batch_create_payments, monitor_payment_status, schedule_payment_reminder) and mix verb forms. The convention is more consistent than not.

    Tool Count2/5

    With 27 tools, the server exceeds the threshold for a well-scoped toolset. While Mercado Pago is a complex platform, the number is high and could overwhelm agents, and several tools could be consolidated (e.g., payment creation variants, reporting tools).

    Completeness4/5

    The toolset covers the core payment lifecycle (create, read, search, cancel, refund), customer management, subscriptions, cards, and adds analytics, fraud, and reporting. Minor gaps exist like no customer update/delete, no subscription cancellation, and no card removal, but these are not critical for basic workflows.

    Maintenance

    ActivityInactive
    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
      30 npm
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects AI agents to MercadoLibre, the largest e-commerce marketplace in Latin America. Search products, get item details, browse categories, track trends, and convert currencies.
      8
      26 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to accept payments in Mexico via Mercado Pago, including OXXO cash vouchers, SPEI bank transfers, cards, and Mercado Pago wallet, through a stateless hosted checkout.
      MIT