mercadopago-mcp
<div align="center">
# mercadopago-mcp
MCP server to inspect Mercado Pago payments, orders, preferences, and webhook signatures from your AI client.
[](https://www.npmjs.com/package/mercadopago-mcp)
[](LICENSE)
[](tsconfig.json)
[](#security-model)
</div>
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
```sh
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.
## 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](https://www.mercadopago.com/developers/panel/app) > 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):
```json
{
"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):
```json
{
"mcpServers": {
"mercadopago": {
"command": "npx",
"args": ["-y", "mercadopago-mcp"],
"env": {
"MP_ACCESS_TOKEN": "APP_USR-your-token"
}
}
}
}
```
### Claude Code
```sh
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:
```json
{
"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`:
```json
"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
```sh
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](LICENSE) © [Matías Sánchez González](https://www.matiasgs.com)
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.