mercado-pago-mcp

hdbookie/mercado-pago-mcp

3.1

If you are the rightful owner of mercado-pago-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Mercado Pago MCP Server is a comprehensive Model Context Protocol server designed for seamless integration with the Mercado Pago API, offering extensive payment processing and customer management capabilities.

Tools
10
Resources
0
Prompts
0

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"
      }
    }
  }
}

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