mcp-culqi

@codespar/mcp-culqi

MCP server for Culqi — Peru's default PSP.

Culqi is the Stripe of Peru: the standard rail for Peruvian D2C brands and SaaS. It ships CulqiOnline (hosted checkout), CulqiLink (payment links), and CulqiFull (subscriptions). Adding Culqi brings Peru into the CodeSpar catalog alongside Mexico, Brazil, Colombia, Argentina, and Chile.

Tools (20)

Tool	Purpose
create_token	Tokenize a card (POST /tokens).
create_charge	Create a charge (POST /charges).
get_charge	Retrieve a charge by Culqi id.
list_charges	List charges (GET /charges) with optional filters.
capture_charge	Capture a previously-authorized charge (POST /charges/{id}/capture).
refund_charge	Refund a captured charge (POST /refunds).
get_refund	Retrieve a refund by id (GET /refunds/{id}).
create_customer	Create a customer record (POST /customers).
get_customer	Retrieve a customer by Culqi id (GET /customers/{id}).
list_customers	List customers (GET /customers) with optional filters passed as query params: first_name, last_name, email,...
create_card	Attach a tokenized card to a customer for reuse (POST /cards).
delete_card	Detach a saved card from its customer (DELETE /cards/{id}).
create_order	Create an order (POST /orders) for non-card payment methods — Yape, PagoEfectivo (Cash), bank transfer.
confirm_order	Confirm an unpaid order (POST /orders/{id}/confirm).
list_orders	List orders (GET /orders) with optional filters passed as query params: order_number, state (created, paid,...
create_plan	Create a subscription plan (POST /plans).
create_subscription	Subscribe a customer's saved card to a plan (POST /subscriptions).
cancel_subscription	Cancel an active subscription (DELETE /subscriptions/{id}).
list_events	List webhook events (GET /events) with optional filters.
get_event	Retrieve a single webhook event by id (GET /events/{id}).

Install

npm install @codespar/mcp-culqi

Environment

CULQI_SECRET_KEY="sk_test_..."   # or sk_live_... for production

Culqi has no separate sandbox URL — the key prefix (sk_test_ vs sk_live_) selects the environment.

Authentication

Bearer token on every request:

Authorization: Bearer <CULQI_SECRET_KEY>
Content-Type: application/json

Base URL: https://api.culqi.com/v2.

Run

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-culqi

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-culqi

Notes

• Amounts are in cents of the currency (e.g. 1000 = S/ 10.00 PEN).
• Currencies supported: PEN, USD.
• Tokenization of raw card data is typically done client-side (culqi.js / mobile SDKs). The create_token tool is primarily for test scripts — never send real PANs from a backend without PCI scope.
• Subscriptions require tyc: true (terms & conditions acceptance) on creation.

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT