Provides AI agents with official sandbox test cards and decline code explanations for Latin American and global payment gateways.
Also known as eyrockscript/test-card-hub, test-card-hub, test-card-hub-mcp
- Stars
- 2
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- 1.1.0
- Last commit
- Nov 12, 2026
- License
- MIT
What is Test Card Hub MCP?
Test Card Hub provides AI agents with official sandbox test cards and decline code explanations for Latin American and global payment gateways. It exposes 7 tools, such as list_gateways, find_test_cards, validate_card.
Summary generated from the project's README
About Test Card Hub MCP server
Test Card Hub provides AI agents with official sandbox test card data and decline code explanations for global and Latin American payment gateways. It supports providers such as Stripe, Mercado Pago MX, Conekta, Openpay MX, NetPay MX, Clip, Kushki MX, PayU Latam MX, dLocal, and Adyen. Developers use this server to facilitate end-to-end checkout testing for various scenarios including approved payments, insufficient funds, and 3DS reviews.
The server is designed for local use with clients like Claude Desktop, Cursor, or Claude Code. It requires Node.js 20 or newer and can be installed via pnpm or npx. Users can also import custom environments by providing a backup file from the companion Chrome extension. All tools are read-only, and the server does not generate card numbers or communicate directly with any payment gateway.
Key tools include find_test_cards for retrieving specific card details, validate_card for checking Luhn compliance, and generate_checkout_tests to create TypeScript Playwright test files. It also features scan_for_real_cards to identify potential real card numbers in logs or code and explain_decline to interpret gateway error codes.
What you can do with it
- 1Automated checkout testingGenerate a Playwright test file in TypeScript that covers every sandbox scenario for a specific gateway.
- 2Error code interpretationGet the official meaning of a payment decline and a suggested message for customers in English or Spanish.
- 3Security scanningScan code or logs to find card numbers that might be real by checking Luhn validity and brand recognition.
Written from the project's README. Every use case is checked against a quote from it.
How to install Test Card Hub MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Test Card Hub MCP in Claude Code
$ claude mcp add test-card-hub -- npx -y test-card-hub-mcpInstall Test Card Hub MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"test-card-hub": {
"command": "npx",
"args": [
"-y",
"test-card-hub-mcp"
]
}
}
}Install Test Card Hub MCP in VS Code
.vscode/mcp.json
{
"servers": {
"test-card-hub": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"test-card-hub-mcp"
]
}
}
}Install Test Card Hub MCP in VS Code CLI
$ code --add-mcp '{"name":"test-card-hub","type":"stdio","command":"npx","args":["-y","test-card-hub-mcp"]}'Install Test Card Hub MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"test-card-hub": {
"command": "npx",
"args": [
"-y",
"test-card-hub-mcp"
]
}
}
}Install Test Card Hub MCP in Codex
$ codex mcp add test-card-hub -- npx -y test-card-hub-mcpInstall Test Card Hub MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.test-card-hub] command = "npx" args = ["-y", "test-card-hub-mcp"]
Install Test Card Hub MCP in Gemini CLI
$ gemini mcp add -s user test-card-hub npx -- -y test-card-hub-mcpInstall Test Card Hub MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"test-card-hub": {
"command": "npx",
"args": [
"-y",
"test-card-hub-mcp"
]
}
}
}Test Card Hub MCP tools 7
Detected from the READMElist_gatewaysfind_test_cardsvalidate_cardlist_environmentsgenerate_checkout_testsscan_for_real_cardsexplain_decline
| list_gateways | — | |
| find_test_cards | — | |
| validate_card | — | |
| list_environments | — | |
| generate_checkout_tests | — | |
| scan_for_real_cards | — | |
| explain_decline | — |
Configuration
TEST_CARD_HUB_BACKUPOptional path to the backup JSON exported from the Test Card Hub Chrome extension, to expose your own environments.
| Name | Description | |
|---|---|---|
| TEST_CARD_HUB_BACKUP | Optional path to the backup JSON exported from the Test Card Hub Chrome extension, to expose your own environments. |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubtest-card-hub-mcp
MCP server that gives AI agents the official sandbox test cards of Latin American and global payment gateways, so they can test a checkout end to end: approved, declined, insufficient funds and 3DS/review scenarios.
Companion to the Test Card Hub Chrome extension. Same data, same validation code.
Gateways: Stripe, Mercado Pago MX, Conekta, Openpay MX, NetPay MX, Clip, Kushki MX, PayU Latam MX, dLocal and Adyen. Every number is copied from the gateway's official documentation, with the URL and verification date (sources).
Test environments only. The server never generates card numbers and never calls a gateway.
Install
Claude Code:
claude mcp add test-card-hub -- pnpm dlx test-card-hub-mcp
Claude Desktop, Cursor and other clients (mcpServers config):
{
"mcpServers": {
"test-card-hub": {
"command": "pnpm",
"args": ["dlx", "test-card-hub-mcp"]
}
}
}
npx -y test-card-hub-mcp works too. Requires Node.js 20 or newer.
Desktop apps (Claude Desktop, Cursor) do not load your shell profile. If Node.js comes from nvm, fnm or asdf, the app cannot find node and the server fails with env: node: No such file or directory. Pass your Node.js bin directory in env.PATH (find it with dirname "$(which node)"):
{
"mcpServers": {
"test-card-hub": {
"command": "pnpm",
"args": ["dlx", "test-card-hub-mcp"],
"env": {
"PATH": "/Users/you/.nvm/versions/node/v22.23.4/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
}
}
}
}
Tools
| Tool | What it does |
|---|---|
list_gateways |
Gateways with docs URL, verification date, card count per outcome and the gateway hint (expiry, CVV, cardholder-name rules). |
find_test_cards |
Cards filtered by gateway, outcome, brand, environment or source. Each card includes everything to type in the checkout: expiry, CVV, postal code, and the fields some sandboxes need, such as the NetPay customer email or the Mercado Pago, PayU and Adyen cardholder name. Max 50 per call; the response says how many matched. |
validate_card |
Luhn, length, brand and whether the number is a known test number. Verdict possibly_real_card tells the agent to stop. |
list_environments |
Your own environments from the extension, read from an exported backup file. |
generate_checkout_tests |
Writes a Playwright test file (TypeScript) with one test per sandbox scenario of a gateway, with every field filled from the official rules. Map the fillCheckout and expectOutcome helpers to your checkout's selectors. The server returns the file; it writes nothing to disk. |
scan_for_real_cards |
Scans text (code, fixtures, logs, seed data) for card numbers that may be real: Luhn-valid, a known brand, and not a published sandbox number. Findings are masked to first 6 + last 4 digits (last 4 only for numbers under 16 digits), with line and column. Numbers split across lines or separated by dots are not detected. Up to 200,000 characters per call. |
explain_decline |
Explains a gateway decline or error code: the official meaning with its source URL, plus a suggested customer message (es/en) and merchant action. The suggestions are ours and labelled as such. Omit code to list a gateway's known codes. |
All tools are read-only. Descriptions accept lang: "es" for Spanish texts.
Where the data comes from
Card numbers come from each gateway's official test-card page. Field rules (expiry, CVV, cardholder name, email) and decline codes come from the official docs listed in src/data/gateway-research/<gateway>.json, each with its sources, verifiedAt date and gaps: what the docs did not state. Every scenario says where each value came from (fieldSources: gateway_docs, any_future_date or any_value). Decline categories (insufficient_funds, fraud_suspected, ...) are our classification; gateways do not publish them.
Known gaps on 2026-11-10: Kushki's docs are behind a password, so explain_decline has no Kushki codes and its field rules could not be re-verified. Gateways do not document which decline code each sandbox scenario returns, so generate_checkout_tests checks the outcome shown to the customer, not a specific code.
Prompt checkout_test_matrix (checkoutUrl, gateway): runs every outcome against your checkout with a browser tool such as Playwright MCP and returns a pass/fail table.
Use with Playwright MCP
claude mcp add playwright -- pnpm dlx @playwright/mcp@latest
claude mcp add test-card-hub -- pnpm dlx test-card-hub-mcp
Then ask: "Test the checkout at http://localhost:3000/pay with Conekta: approved, declined and insufficient funds."
Your own environments
- In the extension, open "Manage environments" and click "Export backup".
- Start the server with the file path:
claude mcp add test-card-hub -- pnpm dlx test-card-hub-mcp --backup /path/to/test-card-hub-backup.json
Or set TEST_CARD_HUB_BACKUP=/path/to/file.json. The file is re-read on every call, so a new export is picked up without restarting. The path comes only from server configuration, never from a tool argument.
Español
Servidor MCP con las tarjetas de prueba oficiales de pasarelas de pago (Stripe, Mercado Pago, Conekta, Openpay, NetPay, Clip, Kushki, PayU, dLocal, Adyen) para que un agente de IA pruebe un checkout de punta a punta. Instalación en Claude Code:
claude mcp add test-card-hub -- pnpm dlx test-card-hub-mcp
Usa lang: "es" para recibir descripciones y notas en español. Para tus propios ambientes, exporta el respaldo desde la extensión y pasa la ruta con --backup.
Development
pnpm install
pnpm --filter test-card-hub-mcp test:coverage
src/domain, src/data and src/ui/view-model.js of the extension are copied into mcp/core by scripts/sync-core.mjs before tests and before packing. Do not edit mcp/core.
Made by Cenzontle. MIT license.
Test Card Hub MCP questions
How do I add Test Card Hub MCP to Claude Code?
Run claude mcp add test-card-hub -- npx -y test-card-hub-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Test Card Hub MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Test Card Hub MCP provide?
It exposes 7 tools, including list_gateways, find_test_cards, validate_card, list_environments, generate_checkout_tests.
Does this server generate real credit card numbers?
No, the server only provides official sandbox test cards from gateway documentation and never generates new card numbers or calls a gateway.
Can I use this to generate Playwright tests?
Yes, the server includes a tool to write TypeScript Playwright test files for various sandbox scenarios of a gateway.
How can I scan my code for potential real card numbers?
You can use the scan_for_real_cards tool to scan text like code, logs, or seed data for Luhn-valid numbers that are not known sandbox numbers.
What gateways are supported?
Supported gateways include Stripe, Mercado Pago MX, Conekta, Openpay MX, NetPay MX, Clip, Kushki MX, PayU Latam MX, dLocal, and Adyen.