Mcp Culqi

io.github.codesparPublished by GitHub account codesparv0.2.2Updated Oct 24, 2026

MCP server for Culqi — Peru PSP: charges, refunds, cards, Yape/PagoEfectivo, subscriptions

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Local MCP server for the Culqi payment platform in Peru, letting an assistant create charges, refunds, customers, cards, orders and subscriptions.

What you can do
Create and inspect charges: tokenize a card, create, retrieve, list and capture charges, and issue or look up refunds. Manage customers and saved cards: create and look up customers, attach a tokenized card, detach a saved card. Handle non-card orders: create orders for Yape, PagoEfectivo or bank transfer, confirm unpaid orders and list orders. Run subscriptions: create plans, subscribe a saved card, cancel a subscription. Review webhook events: list and retrieve events.
When to use it
Use it when an assistant needs to work with Culqi payments for Peruvian or USD transactions — for example creating test charges in the sandbox, managing customers and saved cards, or setting up and cancelling subscriptions.
Requirements
Runs locally over stdio via the npm package, so Node.js is needed. Requires a Culqi secret key in the CULQI_SECRET_KEY environment variable; the key prefix selects sandbox or production. Network access to the Culqi API is required.
Before you install
The server holds a Culqi secret key that can move real money when a live key is used; charges, refunds, orders, subscriptions and card deletion all change data. Card tokenization from a backend may require PCI scope, so avoid sending real card numbers. Amounts are in cents, and subscriptions require terms acceptance.

Installation

In SourceWeft

  1. Open Mcp Culqi in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@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)

ToolPurpose
create_tokenTokenize a card (POST /tokens).
create_chargeCreate a charge (POST /charges).
get_chargeRetrieve a charge by Culqi id.
list_chargesList charges (GET /charges) with optional filters.
capture_chargeCapture a previously-authorized charge (POST /charges/{id}/capture).
refund_chargeRefund a captured charge (POST /refunds).
get_refundRetrieve a refund by id (GET /refunds/{id}).
create_customerCreate a customer record (POST /customers).
get_customerRetrieve a customer by Culqi id (GET /customers/{id}).
list_customersList customers (GET /customers) with optional filters passed as query params: first_name, last_name, email,...
create_cardAttach a tokenized card to a customer for reuse (POST /cards).
delete_cardDetach a saved card from its customer (DELETE /cards/{id}).
create_orderCreate an order (POST /orders) for non-card payment methods — Yape, PagoEfectivo (Cash), bank transfer.
confirm_orderConfirm an unpaid order (POST /orders/{id}/confirm).
list_ordersList orders (GET /orders) with optional filters passed as query params: order_number, state (created, paid,...
create_planCreate a subscription plan (POST /plans).
create_subscriptionSubscribe a customer's saved card to a plan (POST /subscriptions).
cancel_subscriptionCancel an active subscription (DELETE /subscriptions/{id}).
list_eventsList webhook events (GET /events) with optional filters.
get_eventRetrieve a single webhook event by id (GET /events/{id}).

Install

bash
npm install @codespar/mcp-culqi

Environment

bash
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

bash
# 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

Source: packages/payments/culqi/README.md at commit d0a519a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts