mcp-kushki — Claude Code MCP server: what it does, how to install
An MCP server that lets an agent call the Kushki payments API: cards, PSE and SPEI transfers, cash and subscriptions. Useful when you build checkout flows for Latin America.
claude mcp add --env KUSHKI_PUBLIC_MERCHANT_ID=<KUSHKI_PUBLIC_MERCHANT_ID> --env KUSHKI_PRIVATE_MERCHANT_ID=<KUSHKI_PRIVATE_MERCHANT_ID> --env KUSHKI_ENV=<KUSHKI_ENV> --transport stdio kushki -- npx -y @codespar/mcp-kushkiWhat mcp-kushki does
This server gives an agent access to the Kushki payments API, which covers Mexico, Colombia, Chile, Peru and Ecuador. It exposes 10 tools. tokenize_card swaps a card for a single-use token, create_charge bills in one step, and create_preauthorization plus capture_preauthorization handle hold-then-capture. void_charge covers voids and refunds.
Bank transfers run through create_transfer_token and create_transfer_charge, which returns a redirect URL. PSE is for Colombia, SPEI for Mexico. Cash payments get a voucher from create_cash_charge, and recurring card billing starts with create_subscription and stops with cancel_subscription.
You need two merchant ids. The public one only tokenizes. The private one moves money, so keep it server-side. KUSHKI_ENV defaults to sandbox, which means nothing real is charged until you set production. Amounts follow Kushki's tax shape: subtotalIva, subtotalIva0, iva and currency.
What it helps with
- run a test card payment through Kushki
- hold funds on a card and capture part of them later
- start a PSE or SPEI bank transfer and get the redirect link
- issue a cash voucher for an OXXO-style network
- set up recurring card billing and cancel it on request
Example prompts for the agent
- Use Kushki to tokenize this test card and charge it in COP with 19% IVA
- Create a Kushki preauthorization for this card, then capture part of it with
capture_preauthorization - Start a PSE transfer through Kushki and give me the redirect URL
How to install mcp-kushki
Platform CLI
claude mcp add --env KUSHKI_PUBLIC_MERCHANT_ID=<KUSHKI_PUBLIC_MERCHANT_ID> --env KUSHKI_PRIVATE_MERCHANT_ID=<KUSHKI_PRIVATE_MERCHANT_ID> --env KUSHKI_ENV=<KUSHKI_ENV> --transport stdio kushki -- npx -y @codespar/mcp-kushkiReplace <…> with your own values
Platform CLI
codex mcp add kushki --env KUSHKI_PUBLIC_MERCHANT_ID=<KUSHKI_PUBLIC_MERCHANT_ID> --env KUSHKI_PRIVATE_MERCHANT_ID=<KUSHKI_PRIVATE_MERCHANT_ID> --env KUSHKI_ENV=<KUSHKI_ENV> -- npx -y @codespar/mcp-kushkiReplace <…> with your own values
Config file
{
"mcpServers": {
"kushki": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-kushki"
],
"env": {
"KUSHKI_PUBLIC_MERCHANT_ID": "<KUSHKI_PUBLIC_MERCHANT_ID>",
"KUSHKI_PRIVATE_MERCHANT_ID": "<KUSHKI_PRIVATE_MERCHANT_ID>",
"KUSHKI_ENV": "<KUSHKI_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"kushki": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-kushki"
],
"env": {
"KUSHKI_PUBLIC_MERCHANT_ID": "<KUSHKI_PUBLIC_MERCHANT_ID>",
"KUSHKI_PRIVATE_MERCHANT_ID": "<KUSHKI_PRIVATE_MERCHANT_ID>",
"KUSHKI_ENV": "<KUSHKI_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e KUSHKI_PUBLIC_MERCHANT_ID=<KUSHKI_PUBLIC_MERCHANT_ID> -e KUSHKI_PRIVATE_MERCHANT_ID=<KUSHKI_PRIVATE_MERCHANT_ID> -e KUSHKI_ENV=<KUSHKI_ENV> kushki npx -y @codespar/mcp-kushkiReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-kushki
How do I install mcp-kushki in Claude Code?
Run `claude mcp add mcp-kushki -e KUSHKI_PUBLIC_MERCHANT_ID=<KUSHKI_PUBLIC_MERCHANT_ID> -e KUSHKI_PRIVATE_MERCHANT_ID=<KUSHKI_PRIVATE_MERCHANT_ID> -- npx -y @codespar/mcp-kushki`. Replace the placeholders with your two merchant ids.
What does mcp-kushki do?
It gives an agent 10 tools for the Kushki payments API: card tokenization, charges and preauthorizations, PSE and SPEI transfers, cash vouchers and subscriptions.
Which credentials does mcp-kushki need?
Two are required: KUSHKI_PUBLIC_MERCHANT_ID for tokenization and KUSHKI_PRIVATE_MERCHANT_ID for anything that moves money. KUSHKI_ENV is optional and defaults to sandbox; set it to production for live traffic.
