# io.github.codespar/mcp-culqi (npm · @codespar/mcp-culqi)

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

- Trust score: 69/100 (medium)
- Change this week: +23
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-04

## Components

- npm · `@codespar/mcp-culqi`: 69/100 (this document), [markdown](https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi.md), [page](https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi)

## Channel facts

- Registry: `npm`
- Package: `@codespar/mcp-culqi`
- Version: `0.2.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-04.

- **Supply Chain Security**: 83/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known medium-severity CVE affects hono 4.12.33, reached via @modelcontextprotocol/sdk > hono. A fixed version is available.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 42 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 77/100
  - AI-judged instruction clarity (excellent).
  - Tool/resource definitions use about 1887 tokens (~94/item across 20 items; 20 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 30/100
  - Stability observed for 9 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add codespar-mcp-culqi -- npx -y @codespar/mcp-culqi
```

### Codex

```bash
codex mcp add codespar-mcp-culqi -- npx -y @codespar/mcp-culqi
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codespar-mcp-culqi": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@codespar/mcp-culqi"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add codespar-mcp-culqi --command npx --arg -y --arg @codespar/mcp-culqi
```

### Hermes

```yaml
mcp_servers:
  codespar-mcp-culqi:
    command: "npx"
    args: ["-y", "@codespar/mcp-culqi"]
```

### Other

```json
{
  "mcpServers": {
    "codespar-mcp-culqi": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-culqi"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-04 (score 69, 0)

- [security regression] CVE-2026-69207 affects this package: medium
- [security regression] Known CVEs: partial → fail

### 2026-08-03 (score 69, +48)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] License: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Stability: unverified → 0.27
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: MIT

### 2026-08-02 (score 21, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-08-01 (score 6, −15)

- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] Dependency health: unverified → partial

### 2026-07-31 (score 21, −3)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 24, −22)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (20)

### `create_token` (~156 tokens)

Tokenize a card (POST /tokens). Returns a token id like tkn_xxx. Tokenization is typically done client-side via culqi.js or mobile SDKs; this tool is primarily for test scripts and integration tests. Never send real PANs from a backend without PCI scope.

Input parameters:

- `card_number` (string, required): PAN (13-19 digits). Never log.
- `cvv` (string, required): Card verification value (3 or 4 digits)
- `email` (string, required): Cardholder email
- `expiration_month` (string, required): Two-digit month (01-12)
- `expiration_year` (string, required): Four-digit year (e.g. 2027)
- `metadata` (object): Optional merchant-side key-value metadata

### `create_charge` (~219 tokens)

Create a charge (POST /charges). Amount is in cents of the currency (e.g. 1000 = S/ 10.00 PEN). source_id accepts a token id (tkn_xxx) or a stored card id (crd_xxx).

Input parameters:

- `amount` (number, required): Amount in cents (e.g. 1000 = S/ 10.00)
- `antifraud_details` (object): Antifraud signals — recommended for live traffic
- `capture` (boolean): true (default) authorizes + captures; false authorizes only
- `currency_code` (string, required): ISO-4217 currency code supported by Culqi
- `description` (string): Human-readable description for the payer
- `email` (string, required): Payer email
- `installments` (number): Installment count for cuotas (0 for single payment)
- `metadata` (object): Merchant-side key-value metadata
- `source_id` (string, required): Token id (tkn_xxx) or saved card id (crd_xxx)

### `get_charge` (~31 tokens)

Retrieve a charge by Culqi id.

Input parameters:

- `id` (string, required): Culqi charge id (chr_xxx)

### `list_charges` (~99 tokens)

List charges (GET /charges) with optional filters. Filters are passed as query params: amount, min_amount, max_amount, installments, currency_code, code (auth code), decline_code, fraud_score, first_name, last_name, email, country_code, creation_date_from (ms), creation_date_to (ms), limit, before, after.

Input parameters:

- `filters` (object): Query filters passed as-is to the Culqi /charges endpoint.

### `capture_charge` (~59 tokens)

Capture a previously-authorized charge (POST /charges/{id}/capture). Use after creating a charge with capture=false. Must be called within 10 days of authorization.

Input parameters:

- `id` (string, required): Culqi charge id to capture (chr_xxx)

### `refund_charge` (~81 tokens)

Refund a captured charge (POST /refunds). Partial refunds supported by setting amount below the charge total.

Input parameters:

- `amount` (number, required): Refund amount in cents
- `charge_id` (string, required): Culqi charge id to refund (chr_xxx)
- `metadata` (object): Optional metadata
- `reason` (string, required): Refund reason (Culqi enum)

### `get_refund` (~38 tokens)

Retrieve a refund by id (GET /refunds/{id}).

Input parameters:

- `id` (string, required): Culqi refund id (ref_xxx)

### `create_customer` (~127 tokens)

Create a customer record (POST /customers). Use the returned customer_id with create_card to save reusable cards.

Input parameters:

- `address` (string, required): Street address
- `address_city` (string, required): City
- `country_code` (string, required): ISO-3166 alpha-2 (e.g. PE)
- `email` (string, required): Customer email (must be unique)
- `first_name` (string, required): Customer first name
- `last_name` (string, required): Customer last name
- `metadata` (object): Merchant-side key-value metadata
- `phone_number` (string, required): Phone, digits only

### `get_customer` (~38 tokens)

Retrieve a customer by Culqi id (GET /customers/{id}).

Input parameters:

- `id` (string, required): Culqi customer id (cus_xxx)

### `list_customers` (~72 tokens)

List customers (GET /customers) with optional filters passed as query params: first_name, last_name, email, country_code, creation_date_from (ms), creation_date_to (ms), limit, before, after.

Input parameters:

- `filters` (object): Query filters passed as-is to the Culqi /customers endpoint.

### `create_card` (~109 tokens)

Attach a tokenized card to a customer for reuse (POST /cards). Returns a card id (crd_xxx) usable as source_id on future charges.

Input parameters:

- `customer_id` (string, required): Culqi customer id (cus_xxx)
- `metadata` (object): Merchant-side key-value metadata
- `token_id` (string, required): Culqi token id from create_token (tkn_xxx)
- `validate` (boolean): Run a 0-amount validation charge on attach (default true)

### `delete_card` (~50 tokens)

Detach a saved card from its customer (DELETE /cards/{id}). The card id becomes unusable as source_id afterwards.

Input parameters:

- `id` (string, required): Culqi card id (crd_xxx)

### `create_order` (~185 tokens)

Create an order (POST /orders) for non-card payment methods — Yape, PagoEfectivo (Cash), bank transfer. Returns an order with CIP / QR data the payer uses to complete payment. Confirm reception via webhooks or confirm_order.

Input parameters:

- `amount` (number, required): Order amount in cents
- `client_details` (object, required): Payer details required for Yape / Cash orders
- `confirm` (boolean): If true, confirms the order immediately on creation (default false)
- `currency_code` (string, required): ISO-4217 currency
- `description` (string, required): Human-readable order description
- `expiration_date` (number, required): Unix epoch seconds for when the order expires (must be ~>10 min ahead)
- `metadata` (object): Merchant-side key-value metadata
- `order_number` (string, required): Merchant-side unique order number (3-80 chars)

### `confirm_order` (~59 tokens)

Confirm an unpaid order (POST /orders/{id}/confirm). Moves the order to a confirmed state ready to be paid by the customer via Yape / PagoEfectivo.

Input parameters:

- `id` (string, required): Culqi order id (ord_xxx)

### `list_orders` (~75 tokens)

List orders (GET /orders) with optional filters passed as query params: order_number, state (created, paid, expired, deleted, failed), creation_date_from (ms), creation_date_to (ms), limit, before, after.

Input parameters:

- `filters` (object): Query filters passed as-is to the Culqi /orders endpoint.

### `create_plan` (~146 tokens)

Create a subscription plan (POST /plans). Plans are reusable templates — attach customer cards via create_subscription.

Input parameters:

- `amount` (number, required): Amount charged per interval, in cents
- `currency_code` (string, required): Plan currency
- `description` (string): Plan description
- `initial_cycles` (object): Optional intro pricing for the first N cycles
- `interval_count` (number, required): Number of interval units between charges (e.g. 1 = every month)
- `interval_unit_time` (string, required): Billing interval unit
- `metadata` (object): Merchant-side key-value metadata
- `name` (string, required): Full plan name
- `short_name` (string, required): Short/display name

### `create_subscription` (~102 tokens)

Subscribe a customer's saved card to a plan (POST /subscriptions). Requires tyc=true (terms & conditions acceptance).

Input parameters:

- `card_id` (string, required): Culqi card id (crd_xxx) from create_card
- `metadata` (object): Merchant-side key-value metadata
- `plan_id` (string, required): Culqi plan id (pln_xxx) from create_plan
- `tyc` (boolean, required): Customer accepted terms & conditions. Must be true.

### `cancel_subscription` (~35 tokens)

Cancel an active subscription (DELETE /subscriptions/{id}).

Input parameters:

- `id` (string, required): Culqi subscription id (sub_xxx)

### `list_events` (~89 tokens)

List webhook events (GET /events) with optional filters. Filters are passed through as query params: event_type, creation_date_from, creation_date_to, limit, before, after.

Input parameters:

- `filters` (object): Query filters passed as-is: event_type (e.g. 'charge.creation.succeeded'), creation_date_from (ms timestamp), creation_date_to (ms timestamp), limit, before, after.

### `get_event` (~50 tokens)

Retrieve a single webhook event by id (GET /events/{id}). Useful for auditing a webhook delivery against Culqi's canonical record.

Input parameters:

- `id` (string, required): Culqi event id (evt_xxx)

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi#diagnostics

## Score history

- 2026-08-04: 69
- 2026-08-03: 69
- 2026-08-02: 21
- 2026-08-01: 6
- 2026-07-31: 21
- 2026-07-30: 24
- 2026-07-28: 46
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/@codespar/mcp-culqi
- Socket report: https://socket.dev/npm/package/@codespar/mcp-culqi
- Repository: https://github.com/codespar/mcp-dev-latam
- Changelog RSS feed: https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi/changelog.json
- HTML version of this page: https://verifymcp.io/servers/codespar-mcp-culqi/codespar-mcp-culqi