mcp-culqi — Claude Code MCP server: what it does, how to install
An MCP server for Culqi, Peru's payment provider: charges, refunds, saved cards, Yape and PagoEfectivo orders, subscription plans.
claude mcp add mcp-culqi -e CULQI_SECRET_KEY=<CULQI_SECRET_KEY> -- npx -y @codespar/mcp-culqiWhat mcp-culqi does
The server wraps Culqi API v2 in 20 tools. Card work follows the usual sequence: tokenize, charge, capture if the charge was only authorized, then refund when needed. Customers and their saved cards get their own tools so a card can be reused later.
Payment methods that skip cards run through orders. create_order handles Yape, PagoEfectivo and bank transfers, and confirm_order closes an unpaid one. Plans and subscriptions have their own tools, with one catch: subscription creation needs tyc: true, the customer's acceptance of terms, otherwise it fails. Amounts arrive in the currency's minor units, and PEN and USD are accepted.
Set CULQI_SECRET_KEY before starting the server. Culqi has no separate sandbox host; the prefix decides which environment you hit, sk_test_ or sk_live_. Card tokenization is exposed as create_token, but it is meant for test scripts. Sending real card numbers from your backend without PCI scope is not something to do, and the README says so.
What it helps with
- charge a card and check whether it went through
- refund a charge that was captured earlier
- save a card to a customer for repeat payments
- open an order paid by Yape or PagoEfectivo
- create a plan and attach a subscriber to it
Example prompts for the agent
- Charge this tokenized card 2500 PEN and capture it
- Find the charge with
list_chargesand refund it - Create a customer, then attach the new token as a card
How to install mcp-culqi
Platform CLI
claude mcp add mcp-culqi -e CULQI_SECRET_KEY=<CULQI_SECRET_KEY> -- npx -y @codespar/mcp-culqiReplace <…> with your own values
Platform CLI
codex mcp add culqi --env CULQI_SECRET_KEY=<CULQI_SECRET_KEY> -- npx -y @codespar/mcp-culqiReplace <…> with your own values
Config file
{
"mcpServers": {
"culqi": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-culqi"
],
"env": {
"CULQI_SECRET_KEY": "<CULQI_SECRET_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"culqi": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-culqi"
],
"env": {
"CULQI_SECRET_KEY": "<CULQI_SECRET_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CULQI_SECRET_KEY=<CULQI_SECRET_KEY> culqi npx -y @codespar/mcp-culqiReplace <…> 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-culqi
How do I install mcp-culqi in Claude Code?
Run claude mcp add mcp-culqi -e CULQI_SECRET_KEY=<CULQI_SECRET_KEY> -- npx -y @codespar/mcp-culqi. Alternatively use the stdio transport: claude mcp add --env CULQI_SECRET_KEY=<CULQI_SECRET_KEY> --transport stdio culqi -- npx -y @codespar/mcp-culqi.
What does mcp-culqi do?
It exposes Culqi's payment API as agent tools: tokens, charges, refunds, customers, cards, orders, plans, subscriptions and webhook events.
How do I switch from test to live payments?
The key prefix sets the mode, since Culqi shares one host. Use sk_test_ in CULQI_SECRET_KEY for test traffic and sk_live_ for production.
