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

Option 1: NPX (Easiest - Recommended)

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

Staging/Sandbox (Recommended for Testing)

{
  "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_payment_link

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