Pokémon TCG API

Tarjetas Pokémon TCG de solo lectura, sets, ilustradores y precios (Cardmarket EUR, TCGplayer USD, cada uno con fuente y fecha), líneas de impresión occidentales, japonesas y chinas, búsqueda de tarjetas desde una foto.

GitHubPrueba este MCPPatrocinado

Documentación

@pokemontcgapi/mcp

Un servidor MCP para la API de Pokémon TCG en pokemontcgapi.com. Proporciona a un agente ocho herramientas sobre todo el catálogo: líneas de impresión internacionales, japonesas y chino simplificado, nombres de cartas en ocho idiomas, ilustradores, imágenes y precios que llevan su fuente, base, grado y tamaño de muestra. Los recuentos actuales están en vivo en /v1/status y desglosados en coverage.json.

No oficial. No producido, respaldado, apoyado ni afiliado con Nintendo, Creatures Inc., GAME FREAK inc. o The Pokémon Company International. Pokémon y todas las marcas relacionadas son marcas comerciales de sus respectivos propietarios.

Obtener una clave

Genera la Idempotency-Key una vez por registro y consérvala con el cuerpo de la solicitud:

IDEM=$(uuidgen)

curl -s -X POST "https://api.pokemontcgapi.com/v1/accounts/free" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"email":"you@example.com"}'

¿Perdiste la respuesta? Repite exactamente la misma solicitud (misma Idempotency-Key, mismo cuerpo byte a byte, misma red: misma IPv4 pública o la misma IPv6 /64) dentro de 24 horas y la respuesta regresa, si está almacenada, incluido el secreto; es la respuesta original, por lo que una clave rotada o revocada desde entonces no se revive. Una nueva Idempotency-Key para el mismo correo devuelve 409 ACCOUNT_EXISTS; la misma clave con un cuerpo diferente devuelve 409 IDEMPOTENCY_CONFLICT.

Solo almacenamos un hash de la clave; la respuesta de registro se conserva durante 24 horas para que la misma solicitud pueda reproducirse. Guarda data.key.secret ahora.

Si la reproducción no está disponible, inicia sesión y rota la clave, o usa /v1/accounts/recover con un correo ya verificado para obtener un nuevo secreto.

La clave regresa en data.key.secret. Confirmar la dirección que enviamos por correo eleva la prueba de 80 a 800 créditos, y la prueba termina 30 días después del registro. Los planes de pago comienzan en 29 EUR al mes: pricing.

Instalación

Claude Code:

claude mcp add pokemontcgapi --env PTCG_API_KEY=your-key -- npx -y @pokemontcgapi/mcp

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "your-key" }
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${env:PTCG_API_KEY}" }
    }
  }
}

VS Code — .vscode/mcp.json. Nota que la clave de nivel superior es servers, no mcpServers, y inputs mantiene la clave fuera del archivo confirmado:

{
  "inputs": [
    { "id": "ptcg-key", "type": "promptString", "description": "pokemontcgapi key", "password": true }
  ],
  "servers": {
    "pokemontcgapi": {
      "command": "npx",
      "args": ["-y", "@pokemontcgapi/mcp"],
      "env": { "PTCG_API_KEY": "${input:ptcg-key}" }
    }
  }
}

Entorno: PTCG_API_KEY, necesaria para siete de las ocho herramientas, y PTCG_BASE_URL (por defecto https://api.pokemontcgapi.com). Node ≥ 20. La excepción es ptcg_get_reference, que lee una ruta pública. ptcg_get_catalogue_status no es una excepción: comienza en la /v1/status pública y luego lee un conjunto por región de impresión, lo que necesita la clave. Sin ella, el servidor inicia y lista sus herramientas, y luego esas siete llamadas regresan pidiéndola.

Las herramientas

Ocho herramientas, no una por endpoint. tools/list está en el contexto del modelo en cada turno, por lo que toda la superficie es de aproximadamente 11 KB, y cada herramienta está diseñada como una pregunta en lugar de como una ruta: el modelo no tiene que encadenar cuatro llamadas para responder una cosa.

Herramienta	Responde
`ptcg_search_cards`	"Cartas de Charizard de sets japoneses", por nombre, set, región, rareza, artista o ventana de lanzamiento
`ptcg_get_cards`	Hasta 100 ids en una llamada; `base1-4` y `bs-4` ambos resuelven
`ptcg_get_card_prices`	Cada observación actual de una carta, con impresión, grado, `as_of` y `sample_n`
`ptcg_list_sets`	"Cada set japonés lanzado en 2024"
`ptcg_get_reference`	Las cadenas exactas para tipos, supertipos y rarezas, para que los filtros no se adivinen
`ptcg_list_artists`	Ilustradores y cuántas cartas dibujó cada uno
`ptcg_get_catalogue_status`	Lo que el catálogo contiene y no contiene, medido en vivo
`ptcg_identify_card_from_image`	"¿De qué carta es esta foto?" — candidatos clasificados, y una negativa explícita cuando las reimpresiones comparten la ilustración. 25 créditos por llamada, e incluido desde el plan Growth hacia arriba

Cada herramienta está anotada con readOnlyHint: true y destructiveHint: false. Nada aquí escribe. ptcg_identify_card_from_image es la única marcada con idempotentHint: false, porque la misma foto cuesta 25 créditos cada vez que se envía — un cliente no debe reintentarla por su cuenta.

Las negativas comerciales ponen next_step.handoff en la primera línea del resultado de la herramienta, seguido del mensaje de la API y los detalles completos. Muestra esa frase y su URL al propietario de la cuenta textualmente y no reintentes. El propietario completa el pago, la verificación de correo o el paso de contacto.

Importar un catálogo de cartas

Para una importación completa de cartas, usa la API REST directamente: GET /v1/cards?limit=250&orderBy=id, luego sigue links.next textualmente. La lista plana llena páginas a través de los límites de los sets y usa menos solicitudes que un bucle de cartas separado para cada set. Añade include=translations para nombres al costo del catálogo plano. Los incluidos con precio tienen tarifas separadas. Para una sola región de impresión, añade q=set.region:JP o q=set.region:CN; lang solo selecciona una traducción de nombre. Usa /v1/sets/{code}/cards cuando necesites un set particular y /v1/sets?region=JP para explorar los metadatos de los sets.

El quickstart contiene tanto bucles de paginación como mediciones fechadas. La guía de migración explica cómo capturar un marcador de agua del feed de cambios antes de importar y mantener la réplica después. La herramienta de búsqueda MCP está destinada a búsquedas interactivas acotadas; su argumento region se envía a la API como set.region:JP (o CN, WEST), por lo que una búsqueda japonesa lee solo filas japonesas. Usa REST para una importación completa.

Lo que esta API no tiene

La última herramienta existe debido a esta sección, y devuelve estos hechos desde una llamada en vivo en lugar de dejar que un modelo los infiera:

Sin cartas coreanas. Cero sets KR y cero traducciones ko. La región de impresión y la configuración regional están modeladas en el esquema y no contienen datos, por lo que filtrar por ellas devuelve un resultado vacío, no un error.
El texto del juego de cartas está en inglés y es desigual. attacks, abilities, weaknesses, resistances, subtypes, retreat_cost, rules y flavor_text contienen filas desde el 3 de septiembre de 2026, en las 20,725 impresiones occidentales. Medido el 16 de septiembre de 2026 contra 57,450 cartas: attacks en el 29.9% de todo el catálogo y el 82.9% de la parte occidental, subtypes 35.0%, weaknesses 28.0%, flavor_text 17.9%, abilities 7.0%, rules 5.1%. Las impresiones japonesas y chinas no contienen ninguna, por lo que un attacks nulo significa que no lo tenemos, nunca que la carta no tenga ataque.
Sin legalidades de formato. El objeto de carta no lleva campo legalities, y level está vacío. Si la pregunta es sobre legalidad de mazo, esta API no puede responderla.

Los tres están medidos, fechados en la fuente y repetidos textualmente en las descripciones de las herramientas, por lo que un agente es informado antes de llamar en lugar de después.

Leer precios correctamente

No hay filtro de impresión. Primera edición, ilimitada, holofoil, reverse holofoil y filas con grado todas regresan juntas, así que lee printing, condition y grading en cada fila en lugar de tomar el primer número. basis separa GUIDE (publicado aguas arriba) de DERIVED (calculado por nosotros); PTCG_INDEX es nuestro propio compuesto en EUR y lleva sample_n. Cada observación tiene una fecha as_of y está retrasada al menos un día — nunca cotices un precio sin ella.

Lo que el plan retiene se nombra en lugar de ocultarse: graded y non_english_locales para una clave de prueba, graded en Developer, nada desde Growth hacia arriba. La API lo dice en meta.withheld en la ruta de precios, en el encabezado X-Plan-Withheld cuando los precios viajan en una carta, y en un campo de nivel superior withheld en el lote. Así que una carta sin filas con grado puede ser el plan hablando, no el catálogo.

Para ptcg_get_cards, el campo missing de la API es autoritativo cuando está presente, incluidos sus valores suggested_id. La herramienta mantiene su array existente missing de cadenas y añade missing_details, un array de { id, suggested_id? }; el texto también muestra cada sugerencia. Si la API omite missing, la herramienta recurre a comparar los ids solicitados con los id y legacy_id devueltos, ignorando mayúsculas y minúsculas e ids repetidos. Esto soporta versiones anteriores de la API sin otra solicitud, pero no puede descubrir sus colisiones de set canónico no reportadas ni sugerencias. La API actual omite missing cuando cada id resuelve, por lo que ese respaldo devuelve un array vacío. ptcg_get_card_prices lee una carta con sus precios, por lo que las exclusiones llegan en ese encabezado.

Disciplina de contexto

Los resultados están limitados a 50 filas independientemente de lo que permita la API, enviados como tablas alineadas en lugar de JSON, con una proyección de campos compacta. Una tabla es más corta que las mismas filas como JSON porque las claves no se repiten en cada fila; no publicamos un porcentaje, porque no tenemos una medición reproducible para mostrar junto a él. La truncación siempre se anuncia junto con el cursor para continuar. Las filas de precios son lo único que nunca se trunca.

Protocolo

Construido sobre @modelcontextprotocol/server v2, que negocia la revisión 2025-11-25 y acepta clientes hasta 2024-10-07. Transporte stdio.

La revisión es de la biblioteca, no una afirmación propia: SUPPORTED_PROTOCOL_VERSIONS en @modelcontextprotocol/server@2.0.0 alcanza un máximo en 2025-11-25, por lo que un cliente que solicite algo más nuevo recibe eso. Verificado contra el paquete publicado, no leído de un changelog.

También disponible

SDK de TypeScript, cero dependencias de tiempo de ejecución: @pokemontcgapi/sdk — fuente
Docs: https://pokemontcgapi.com/docs
Cobertura, medida en vivo: https://pokemontcgapi.com/coverage

Compilar desde la fuente

npm ci
npm run typecheck
npm run build

Node >= 20. npm test ejecuta las pruebas unitarias en tests/. Lo que CI aplica es que el paquete verifica tipos y compila tanto en Node 20 como en Node 22, y que npm pack produce la lista de archivos que el registro debe recibir.

Este paquete se desarrolla dentro del monorepo privado que ejecuta pokemontcgapi.com y se refleja aquí en cada lanzamiento, por lo que una solicitud de extracción fusionada viaja a mano en lugar de con un botón de fusión. Eso no es una razón para enviar parches a otro lugar — abre el problema o la PR aquí, es la dirección que se lee.

Licencia

MIT. Los datos servidos por la API llevan términos de redistribución por fuente — consulta https://pokemontcgapi.com/legal/attribution.