ptcgp-mcp-server
Uses GitHub as a third-party source for Pokémon TCG Pocket catalog synchronization and enrichment, including meta deck data queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ptcgp-mcp-server Show me my collection stats for rare cards"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ptcgp-mcp-server
Servidor MCP local para un catálogo de Pokémon TCG Pocket y una colección personal en SQLite. Usa el estándar MCP con transporte stdio; no depende de Claude, Anthropic, OpenAI ni de ningún modelo concreto — cualquier cliente compatible con MCP puede lanzar el proceso.
Este es un proyecto en fase de preparación, todavía no publicado. No lo instales pensando en usarlo como paquete público: hoy es un checkout local (package.json marcado como "private": true, sin remoto Git configurado).
Qué funciona hoy (verificado)
Arranca como servidor MCP sobre stdio y expone 17 tools (tabla más abajo). Verificado con
npm run smoke, que levanta el binario compilado contra un directorio de datos temporal y lista las tools reales.Crea una base SQLite local en
PTCGP_DATA_DIR(o en~/.local/share/ptcgp-mcppor defecto) con WAL, claves foráneas y migraciones versionadas forward-only.Todas las escrituras de colección (individual, masiva, por rango) usan sentencias SQL parametrizadas y corren dentro de una transacción cuando afectan a varias filas.
Las rondas de captura validan un contador de cabecera contra los huecos detectados/confirmados y solo aplican cambios a la colección de forma transaccional, con
confirm=trueexplícito.Normaliza capturas PNG/JPEG/WebP (con corrección de orientación) y ejecuta OCR local con Tesseract; ninguna imagen sale de la máquina. HEIC/HEIF está en la lista de formatos aceptados en el código pero no está soportado por el build de Sharp instalado en este entorno — no lo des por bueno sin comprobarlo tú mismo.
Incluye tools de sincronización/enriquecimiento de catálogo y de consulta de mazos meta, que dependen de fuentes de red de terceros (GitHub, TCGdex, Limitless TCG) y son la parte menos robusta del proyecto: ver OPEN_SOURCE_GAP_ANALYSIS.md para el detalle de por qué.
Related MCP server: mcp-tcgdex
Instalación para desarrollo
Node 22 o 24 (.nvmrc fija 24 como preferido; CI cubre ambas). better-sqlite3 es una dependencia nativa: tras cambiar de versión de Node, vuelve a instalar.
npm ci
export PTCGP_DATA_DIR="$(mktemp -d)"
npm test
npm run smokenpm testcompila y ejecuta la suite (node --test) sobre un directorio de datos que tú controlas.npm run smokearranca el servidor stdio compilado en un directorio temporal propio, lista sus tools y ejecutaPRAGMA quick_checksobre esa base temporal.npm run verifyañade formato (prettier --check), lint (eslint) ynpm pack --dry-run— no publica nada.
Nunca ejecutes tests, sync o rondas contra tu PTCGP_DATA_DIR real sin backup previo.
Configurar un cliente MCP
{
"command": "node",
"args": ["/ruta/absoluta/a/ptcgp-mcp-server/dist/index.js"],
"env": {
"PTCGP_DATA_DIR": "/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data"
}
}El servidor usa stdout exclusivamente para el protocolo MCP; nunca escribas ahí manualmente. PTCGP_LOG_LEVEL acepta fatal|error|warn|info|debug|trace|silent (por defecto info) y controla logs estructurados en stderr — hoy el logging operativo es mínimo (solo arranque/errores fatales), así que no confíes en él para depurar el comportamiento de una tool concreta todavía.
Transporte HTTP (fase inicial)
Existe un segundo entrypoint pensado para clientes remotos (ChatGPT en Developer Mode, MCP Inspector desde otra máquina, etc.). Expone en /mcp el mismo McpServer pero registrando solo 7 tools de lectura (ptcgp_search_cards, ptcgp_get_card, ptcgp_list_expansions, ptcgp_collection_stats, ptcgp_missing_cards, ptcgp_meta_decks, ptcgp_get_decklist). Las 17 tools de stdio siguen intactas.
Arranque local:
export PTCGP_HTTP_TOKEN="$(openssl rand -hex 32)"
export PTCGP_DATA_DIR=/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data
npm run start:http # escucha en 127.0.0.1:8787 por defectoPrueba con el Inspector: npm run inspect:http (pasa el token en Authorization: Bearer … en la UI). El binario stdio se sigue publicando en bin; el HTTP no.
Guardias implementadas dentro del server:
Token estático obligatorio comparado con
crypto.timingSafeEqual.Allowlist de
Host(defensa contra DNS rebinding) y deOrigin(por defecto vacía → deniega cualquier cross-site).Body limit y timeout configurables por env.
Rate limit en memoria por IP (60 peticiones/minuto/IP por defecto), antes de autenticar.
Solo
POST/GETen/mcp; el resto devuelve405con JSON-RPC válido.GET /healthzdevuelve200 text/plain "ok"sin filtrar rutas ni versión.
Fuera de alcance de esta fase: OAuth 2.1, acceso multiusuario, publicación en directorios MCP y despliegue automatizado. Antes de exponer datos privados a un endpoint público real hace falta OAuth 2.1 según el spec MCP. Para pruebas privadas puedes tunelizar con OpenAI Secure MCP Tunnel o Cloudflare Tunnel y el token estático. Los templates de systemd, Caddy y environment file viven en deploy/.
Variables (todas opcionales salvo PTCGP_HTTP_TOKEN): PTCGP_HTTP_HOST (default 127.0.0.1), PTCGP_HTTP_PORT (default 8787), PTCGP_HTTP_TOKEN (>= 32 caracteres, obligatoria), PTCGP_HTTP_ALLOWED_HOSTS (CSV, default localhost,127.0.0.1), PTCGP_HTTP_ALLOWED_ORIGINS (CSV, default vacío), PTCGP_HTTP_BODY_LIMIT_KIB (default 1024), PTCGP_HTTP_REQUEST_TIMEOUT_MS (default 30000), PTCGP_HTTP_RATE_LIMIT_MAX (default 60), PTCGP_HTTP_RATE_LIMIT_WINDOW_MS (default 60000) y PTCGP_HTTP_RATE_LIMIT_MAX_KEYS (default 10000).
Tools MCP
Grupo | Tools |
Catálogo |
|
Colección |
|
Mazos |
|
Rondas de captura |
|
Flujo seguro de una ronda: round_start → round_analyze_screenshots → revisión humana con round_record → round_status → round_finalize(confirm=true). La comprobación de contadores protege contra muchas lecturas incompletas, pero no prueba por sí sola que las capturas cubran toda la expansión: la revisión visual sigue siendo obligatoria.
Datos y privacidad
No se versiona ninguna base de datos, backup, captura real,
.envni log —.gitignorelos excluye y esto se verificó contragit ls-files, no solo se asume.Haz backup de una base SQLite con WAL usando herramientas conscientes de SQLite y con el servidor parado; copiar solo el
.dbmientras está activo puede dejarlo inconsistente.El proyecto no requiere ninguna clave de API. Está bajo licencia MIT pero marcado
"private": truepara evitar una publicación accidental en npm mientras dure esta fase de preparación.
Límites actuales
No hay CLI, transporte Streamable HTTP, backup/restore como funcionalidad del servidor, ni proceso de publicación. Las tools que dependen de red (sync de catálogo, enriquecimiento, mazos meta) no tienen tests de contrato ni protección ante cambios de esquema/maquetación upstream. Antes de ampliar el proyecto, lee HANDOFF.md, ARCHITECTURE.md, ROADMAP.md y OPEN_SOURCE_GAP_ANALYSIS.md.
Available Tools
17 toolsptcgp_bulk_update_collectionActualización masivaADestructive
Actualiza la cantidad poseída de múltiples cartas en una sola llamada transaccional. Cada item: {card_id, quantity}. mode='set' fija valores, mode='add' suma. Ideal al procesar capturas de pantalla de la colección o dictados del usuario. Ids inexistentes se reportan en 'errors' sin abortar el resto.
Inputs: items (required), mode.
ptcgp_collection_statsEstadísticas de colecciónARead-onlyIdempotent
Resumen global de la colección del usuario: cartas únicas poseídas vs total del catálogo, copias totales, desglose por expansión y por rareza. Es el punto de partida para cualquier pregunta general tipo "cómo va mi colección".
Inputs: no named parameters.
ptcgp_enrich_catalogEnriquecer catálogo (datos de combate)AIdempotent
Descarga de TCGdex los datos de combate (ataques, habilidades, debilidades, retirada, stage, efectos de trainers) para las cartas que aún no los tienen. Incremental: solo procesa cartas pendientes salvo force=true. Con 'expansion' limita a un set (recomendado para llamadas desde conversación; el catálogo completo tarda minutos y conviene hacerlo con 'npm run sync' en shell). Fuentes en cascada: TCGdex primero, y para lo que TCGdex no cubra (sets recién salidos) scrapea las páginas de carta de Limitless TCG, que siempre tiene los sets nuevos. pending_total=0 significa catálogo completo.
Inputs: force, limit, expansion.
ptcgp_get_cardDetalle de cartaARead-onlyIdempotent
Detalle completo de una carta por id (ej. 'a1-036'): stats, ataques (coste, daño, efecto), habilidades, debilidades, retirada, stage, línea evolutiva, efecto (trainers), copias poseídas e imagen. El campo battle_data indica si la carta tiene datos de combate (sets muy recientes pueden no tenerlos hasta ejecutar ptcgp_enrich_catalog).
Inputs: card_id (required).
ptcgp_get_decklistDecklist de torneo (Limitless)ARead-only
Descarga una decklist real de torneo para un arquetipo (slug de ptcgp_meta_decks) y la cruza con la colección del usuario: cada carta indica 'owned' (copias poseídas) y el resumen 'buildable' dice si el mazo es montable, qué cartas faltan y cuántas. finish_index selecciona qué resultado de torneo usar (0 = mejor finish reciente).
Ejemplo de flujo: ptcgp_meta_decks -> elegir slug -> ptcgp_get_decklist(slug) -> "te faltan 2 Espeon (b3a-020) y 1 Cyrus (a2-150)". Requiere red.
Inputs: slug (required), finish_index.
ptcgp_list_expansionsListar expansionesARead-onlyIdempotent
Lista todas las expansiones del juego con sus sobres y el progreso de colección del usuario en cada una: total de cartas, poseídas únicas y porcentaje. Útil como visión general o para decidir en qué set centrarse.
Inputs: no named parameters.
ptcgp_mark_rangeMarcar rango de cartasADestructive
Marca como poseídas (o ajusta) cartas de una expansión por números: numbers acepta lista y rangos, ej. "1,3,7-15,22". Pensado para volcado rápido manual: "del set a1 tengo de la 1 a la 50 menos la 33" se resuelve con dos llamadas (set 1-50, luego set 33 a 0) o una llamada "1-32,34-50". Números que no existan en la expansión se reportan en 'errors'.
Inputs: numbers (required), expansion (required), mode, quantity.
ptcgp_meta_decksMazos meta (Limitless)ARead-only
Obtiene el ranking actual de arquetipos de mazo de Pokémon TCG Pocket desde Limitless (play.limitlesstcg.com, datos de torneos reales). Devuelve { decks: [{rank, name, slug, count, share}] } donde 'count' es nº de apariciones en torneos y 'share' el porcentaje del meta. El 'slug' se usa con ptcgp_get_decklist para ver la lista concreta. Requiere red.
Inputs: limit.
ptcgp_missing_cardsCartas faltantes / mejor sobreARead-onlyIdempotent
Analiza qué cartas faltan al usuario, agrupadas por sobre (pack), ordenando los sobres por número de faltantes descendente — responde directamente a "qué sobre me conviene abrir". Filtros opcionales por expansión y rareza máxima (ej. max_rarity='d4' ignora ☆/♕, que en la práctica salen por rareza visual, no por pack normal).
Devuelve { packs: [{pack, expansion, missing_count, total_in_pack, missing: [{id, name, rarity}] }] }. Con include_cards=false omite el listado de cartas y devuelve solo el ranking (más compacto).
Inputs: expansion, max_rarity, include_cards, limit_per_pack.
ptcgp_round_analyze_screenshotsAnalizar capturas de una rondaAIdempotent
Analiza capturas móviles PNG/JPEG/WebP/HEIC, corrige orientación y normaliza cualquier resolución. Detecta los huecos de la cuadrícula y lee sus números con OCR local, sin enviar imágenes a Internet. Las detecciones quedan en revisión y NO cambian la colección. Las rutas deben ir en el mismo orden en que se recorrió la expansión.
Inputs: round_id (required), image_paths (required).
ptcgp_round_finalizeFinalizar y aplicar rondaADestructive
Aplica una ronda completa de forma transaccional. Requiere confirm=true y que el total esperado de poseídas coincida exactamente con total_catálogo - huecos. Por defecto solo usa huecos confirmados; use_auto_detections permite detecciones OCR con confianza >=0.84. En modo minimum conserva cantidades superiores existentes.
Inputs: confirm (required), round_id (required), use_auto_detections, expected_owned_unique.
ptcgp_round_recordConfirmar o corregir una rondaAIdempotent
Registra observaciones confirmadas tras revisar las capturas. missing_numbers son huecos numerados; owned_numbers permite corregir falsos positivos del OCR. En quantity_mode='minimum', una carta visible equivale a cantidad mínima 1. En modo exact debe proporcionarse quantity por carta poseída. Esta operación aún no altera la colección.
Inputs: round_id (required), quantities, owned_numbers, missing_numbers.
ptcgp_round_startIniciar ronda de capturasA
Crea una ronda para una expansión completa. Una ronda empieza en la primera carta y termina en la última captura de esa expansión. expected_owned_unique debe ser la suma de los contadores visibles de la cabecera (diamantes + estrellas + shiny/corona); se usa para impedir que un OCR incompleto altere la colección. quantity_mode='minimum' es el adecuado para la cuadrícula normal: una carta visible prueba al menos una copia y conserva cantidades superiores ya registradas.
Inputs: expansion (required), label, quantity_mode, expected_owned_unique.
ptcgp_round_statusEstado y previsualización de rondasARead-onlyIdempotent
Muestra una ronda concreta o las rondas recientes, con capturas, detecciones confirmadas y pendientes. No modifica datos.
Inputs: round_id.
ptcgp_search_cardsBuscar cartasARead-onlyIdempotent
Busca cartas en el catálogo completo de Pokémon TCG Pocket, con cantidad poseída incluida en cada resultado.
Filtros (todos opcionales, combinables):
query: texto parcial del nombre (case-insensitive)
text_search: busca en efectos de ataques, habilidades y cartas trainer (ej. "heal", "discard", "draw")
expansion: id de expansión (a1, a1a, a2, a2a, a2b, a3, a3a, a3b, a4, a4a, a4b, b1, b1a, b2, b2a, b2b, b3, pa, pb)
pack: nombre del sobre (Mewtwo, Charizard, Pikachu, etc.)
rarity: símbolo o alias (d1=◊, d2=◊◊, d3=◊◊◊, d4=◊◊◊◊, s1=☆, s2=☆☆, s3=☆☆☆, crown=♕, promo)
type: Grass|Fire|Water|Lightning|Psychic|Fighting|Darkness|Metal|Dragon|Colorless|Trainer
category: Pokemon|Trainer
stage: Basic|Stage1|Stage2
min_damage: daño mínimo del mejor ataque (para construcción de mazos)
has_ability: true para solo cartas con habilidad
owned_filter: 'all' (defecto) | 'owned' (quantity>0) | 'missing' (quantity=0) | 'duplicates' (quantity>1)
ex: true para solo cartas ex
limit/offset para paginación
Cada resultado incluye max_damage y has_ability. Para ataques/habilidades/efectos completos usa ptcgp_get_card. Los datos de combate provienen de TCGdex; sets muy recientes pueden no tenerlos aún (ejecutar ptcgp_enrich_catalog periódicamente).
Ejemplos: "atacantes de fuego para mi mazo que ya tenga" -> type="Fire", min_damage=100, owned_filter="owned". "cartas que curen" -> text_search="heal".
Inputs: ex, pack, type, limit, +10 more.
ptcgp_set_card_quantityFijar cantidad de una cartaADestructive
Registra cuántas copias de una carta posee el usuario. mode='set' fija el valor exacto (defecto); mode='add' suma (admite negativos para restar, nunca baja de 0). Usa ptcgp_bulk_update_collection para varias cartas o ptcgp_mark_range para rangos de números consecutivos.
Inputs: card_id (required), quantity (required), mode.
ptcgp_sync_catalogSincronizar catálogoAIdempotent
Descarga el catálogo completo de cartas y expansiones desde el dataset comunitario (chase-manning/pokemon-tcg-pocket-cards, scrapeado de Limitless TCG) y actualiza la base local. Ejecutar tras el primer arranque y cuando salga una expansión nueva. No toca la colección del usuario. Requiere red.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
The core resources are separated by domain (catalog, collection, decks, round-based OCR import), but several tools blur together: sync_catalog vs enrich_catalog, collection_stats vs list_expansions, and missing_cards vs search_cards with owned_filter=missing all have overlapping coverage and rely heavily on descriptions to disambiguate. The round_* workflow is clearly differentiated.
All tools share the ptcgp_ prefix and snake_case, but the internal convention is mixed: most use verb_object (search_cards, set_card_quantity) while some are noun phrases (collection_stats, missing_cards, meta_decks) and the round tools are noun-first (round_start, round_finalize). Still readable, but not a consistent verb_noun pattern throughout.
17 tools is slightly above the ideal range, but the scope is broad enough that most tools earn a place: catalog sync/enrich, card searching, collection updates, deck data, and a deliberate OCR round workflow. It feels somewhat heavy, especially with five round_* tools, but not bloated.
The surface covers the full collection-management lifecycle: ingest catalog, search/get cards, track owned quantities, analyze missing cards, and import via OCR rounds, plus metagame deck lookup. Minor gaps exist such as no way to discard/delete a round or manage custom saved decks, but these are workable and outside the core stated purpose.
Maintenance
Related MCP Connectors
Look up Pokemon TCG Pocket cards, sets, packs, and evaluate decks with battle simulations.
Connect to your CollectHolo Pokémon card collection. Check your portfolio value, look up card, sealed and graded (PSA/BGS/CGC) prices from Cardmarket, TCGplayer, eBay, Goldin and Fanatics, search the catalog in six languages, import a whole collection from a spreadsheet, and add or update holdings in plain language. Every change asks for confirmation.
Organize and track your Magic: The Gathering collection, decks, prices and imports.
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables extraction of structured data from documents like invoices, receipts, and bank statements using local Vision AI (Ollama) or cloud providers (Gemini), with data stored in a local SQLite database.MIT
- AlicenseNot gradedqualityCmaintenanceEnables querying multi-language trading card game data (Pokémon TCG and more) through natural language or direct tools, integrated with Pipeworx MCP gateway.79 npmMIT

@pokemontcgapi/mcpofficial
AlicenseAqualityBmaintenanceEnables agents to search and query Pokémon TCG cards and sets, retrieve priced card data with provenance, and identify cards from images through eight read-only tools.8368 npmMIT- AlicenseAqualityBmaintenanceLets AI assistants search every Pokémon TCG Pocket card by name, type, rarity, set, evolution stage, ability effect and attack, in six languages, with typo tolerance and semantic search.1MIT