Pokémon TCG API

Cartas, conjuntos, ilustradores e preços de Pokémon TCG somente leitura (Cardmarket EUR, TCGplayer USD, cada um com fonte e data), linhas de impressão ocidentais, japonesas e chinesas, busca de cartas a partir de uma foto.

GitHubExperimente este MCPPatrocinado

Documentação

@pokemontcgapi/mcp

Um servidor MCP para a Pokémon TCG API em pokemontcgapi.com. Ele dá a um agente oito ferramentas sobre todo o catálogo: linhas de impressão internacionais, japonesas e chinês simplificado, nomes de cartas em oito idiomas, ilustradores, imagens e preços que carregam sua fonte, base, grau e tamanho da amostra. As contagens atuais estão disponíveis em /v1/status e detalhadas em coverage.json.

Não oficial. Não produzido, endossado, apoiado ou afiliado à Nintendo, Creatures Inc., GAME FREAK inc. ou The Pokémon Company International. Pokémon e todas as marcas relacionadas são marcas registradas de seus respectivos proprietários.

Obtenha uma chave

Gere a Idempotency-Key uma vez por cadastro e mantenha-a junto com o corpo da solicitação:

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"}'

Perdeu a resposta? Repita exatamente a mesma solicitação (mesma Idempotency-Key, mesmo corpo byte a byte, mesma rede: mesmo IPv4 público ou mesmo IPv6 /64) dentro de 24 horas e a resposta retorna, se armazenada, com o segredo incluído; é a resposta original, então uma chave rotacionada ou revogada desde então não é revivida. Uma nova Idempotency-Key para o mesmo e-mail retorna 409 ACCOUNT_EXISTS; a mesma chave com um corpo diferente retorna 409 IDEMPOTENCY_CONFLICT.

Armazenamos apenas um hash da chave; a resposta do cadastro é mantida por 24 horas para que a mesma solicitação possa ser repetida. Salve data.key.secret agora.

Se a repetição não estiver disponível, entre e rotacione a chave, ou use /v1/accounts/recover com um e-mail já verificado para obter um novo segredo.

A chave retorna em data.key.secret. Confirmar o endereço que enviamos por e-mail eleva o teste de 80 para 800 créditos, e o teste termina 30 dias após o cadastro. Planos pagos começam em 29 EUR por mês: preços.

Instalação

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. Observe que a chave de nível superior é servers, não mcpServers, e inputs mantém a chave fora do arquivo versionado:

{
  "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}" }
    }
  }
}

Ambiente: PTCG_API_KEY, necessária por sete das oito ferramentas, e PTCG_BASE_URL (padrão para https://api.pokemontcgapi.com). Node ≥ 20. A exceção é ptcg_get_reference, que lê uma rota pública. ptcg_get_catalogue_status não é uma exceção: ela começa na /v1/status pública e então lê um conjunto por região de impressão, o que precisa da chave. Sem ela, o servidor inicia e lista suas ferramentas, e então essas sete chamadas retornam pedindo a chave.

As ferramentas

Oito ferramentas, não uma por endpoint. tools/list fica no contexto do modelo a cada turno, então toda a superfície tem cerca de 11 KB, e cada ferramenta é moldada como uma pergunta, não como uma rota — o modelo não precisa encadear quatro chamadas para responder uma coisa.

Ferramenta	Responde
`ptcg_search_cards`	"Cartas de Charizard de conjuntos japoneses", por nome, conjunto, região, raridade, artista ou janela de lançamento
`ptcg_get_cards`	Até 100 ids em uma chamada; `base1-4` e `bs-4` ambos resolvem
`ptcg_get_card_prices`	Cada observação atual para uma carta, com impressão, grau, `as_of` e `sample_n`
`ptcg_list_sets`	"Todos os conjuntos japoneses lançados em 2024"
`ptcg_get_reference`	As strings exatas para tipos, supertipos e raridades, para que filtros não sejam adivinhados
`ptcg_list_artists`	Ilustradores e quantas cartas cada um desenhou
`ptcg_get_catalogue_status`	O que o catálogo contém e o que não contém, medido ao vivo
`ptcg_identify_card_from_image`	"Qual carta é esta na foto?" — candidatos ranqueados, e uma recusa explícita quando reimpressões compartilham a arte. 25 créditos por chamada, e incluído a partir do plano Growth

Cada ferramenta é anotada com readOnlyHint: true e destructiveHint: false. Nada aqui escreve. ptcg_identify_card_from_image é a única marcada com idempotentHint: false, porque a mesma foto custa 25 créditos toda vez que é enviada — um cliente não deve repeti-la por conta própria.

Recusas comerciais colocam next_step.handoff na primeira linha do resultado da ferramenta, seguida pela mensagem da API e detalhes completos. Mostre essa frase e sua URL ao proprietário da conta verbatim e não repita. O proprietário conclui o checkout, a verificação de e-mail ou a etapa de contato.

Importando um catálogo de cartas

Para uma importação completa de cartas, use a API REST diretamente: GET /v1/cards?limit=250&orderBy=id, depois siga links.next verbatim. A lista plana preenche páginas através de limites de conjuntos e usa menos solicitações do que um loop separado de cartas para cada conjunto. Adicione include=translations para nomes ao custo do catálogo simples. Incluídos com preço têm tarifas separadas. Para uma única região de impressão, adicione q=set.region:JP ou q=set.region:CN; lang apenas seleciona uma tradução de nome. Use /v1/sets/{code}/cards quando precisar de um conjunto específico e /v1/sets?region=JP para navegar pelos metadados do conjunto.

O quickstart contém ambos os loops de paginação e medições datadas. O guia de migração explica como capturar um watermark de feed de mudanças antes de importar e manter a réplica depois. A ferramenta de busca MCP é destinada a buscas interativas limitadas; seu argumento region é enviado à API como set.region:JP (ou CN, WEST), então uma busca em japonês lê apenas linhas japonesas. Use REST para uma importação completa.

O que esta API não tem

A última ferramenta existe por causa desta seção, e retorna esses fatos de uma chamada ao vivo em vez de deixar um modelo inferi-los:

Sem cartas coreanas. Zero conjuntos KR e zero traduções ko. A região de impressão e o idioma são modelados no esquema e não carregam dados, então filtrar por eles retorna um resultado vazio, não um erro.
O texto do jogo de cartas está em inglês e é desigual. attacks, abilities, weaknesses, resistances, subtypes, retreat_cost, rules e flavor_text carregam linhas desde 3 de setembro de 2026, nas 20.725 impressões ocidentais. Medido em 16 de setembro de 2026 contra 57.450 cartas: attacks em 29,9% de todo o catálogo e 82,9% da parte ocidental, subtypes 35,0%, weaknesses 28,0%, flavor_text 17,9%, abilities 7,0%, rules 5,1%. Impressões japonesas e chinesas não carregam nenhum, então um attacks nulo significa que não o temos, nunca que a carta não tem ataque.
Sem legalidades de formato. O objeto de carta não carrega campo legalities, e level está vazio. Se a pergunta é sobre legalidade de deck, esta API não pode respondê-la.

Todos os três são medidos, datados na fonte e repetidos verbatim nas descrições das ferramentas, então um agente é informado antes de chamar, não depois.

Lendo preços corretamente

Não há filtro de impressão. Primeira Edição, Ilimitada, holofoil, reverse holofoil e linhas graduadas todas retornam juntas, então leia printing, condition e grading em cada linha em vez de pegar o primeiro número. basis separa GUIDE (publicado upstream) de DERIVED (calculado por nós); PTCG_INDEX é nosso próprio composto em EUR e carrega sample_n. Cada observação tem uma data as_of e é atrasada por pelo menos um dia — nunca cite um preço sem ela.

O que o plano retém é nomeado em vez de oculto: graded e non_english_locales para uma chave de teste, graded no Developer, nada a partir do Growth. A API diz isso em meta.withheld na rota de preços, no cabeçalho X-Plan-Withheld quando preços vêm em uma carta, e em um campo withheld de nível superior no lote. Então uma carta sem linhas graduadas pode ser o plano falando, não o catálogo.

Para ptcg_get_cards, o campo missing da API é autoritativo quando presente, incluindo seus valores suggested_id. A ferramenta mantém seu array existente missing de strings e adiciona missing_details, um array de { id, suggested_id? }; o texto também mostra cada sugestão. Se a API omitir missing, a ferramenta cai para comparar ids solicitados com id e legacy_id retornados, ignorando maiúsculas/minúsculas e ids repetidos. Isso suporta versões mais antigas da API sem outra solicitação, mas não pode descobrir suas colisões de conjunto canônico não relatadas ou sugestões. A API atual omite missing quando todo id resolve, então esse fallback retorna um array vazio. ptcg_get_card_prices lê uma carta com seus preços, então as exclusões chegam nesse cabeçalho.

Disciplina de contexto

Resultados são limitados a 50 linhas independentemente do que a API permite, enviados como tabelas alinhadas em vez de JSON, com uma projeção compacta de campos. Uma tabela é mais curta que as mesmas linhas em JSON porque as chaves não são repetidas em cada linha; não publicamos uma porcentagem, porque não temos uma medição reproduzível para mostrar ao lado dela. A truncagem é sempre anunciada junto com o cursor para continuar. Linhas de preço são a única coisa nunca truncada.

Protocolo

Construído em @modelcontextprotocol/server v2, que negocia a revisão 2025-11-25 e aceita clientes até 2024-10-07. Transporte stdio.

A revisão é da biblioteca, não uma afirmação nossa: SUPPORTED_PROTOCOL_VERSIONS em @modelcontextprotocol/server@2.0.0 atinge o máximo em 2025-11-25, então um cliente que pede algo mais novo recebe isso. Verificado contra o pacote publicado, não lido de um changelog.

Também disponível

SDK TypeScript, zero dependências de runtime: @pokemontcgapi/sdk — fonte
Docs: https://pokemontcgapi.com/docs
Cobertura, medida ao vivo: https://pokemontcgapi.com/coverage

Compilar a partir do código-fonte

npm ci
npm run typecheck
npm run build

Node >= 20. npm test executa os testes unitários em tests/. O que o CI impõe é que o pacote passa no typecheck e compila tanto no Node 20 quanto no Node 22, e que npm pack produz a lista de arquivos que o registro deve receber.

Este pacote é desenvolvido dentro do monorepo privado que executa pokemontcgapi.com e espelhado aqui a cada lançamento, então um pull request mesclado viaja de volta manualmente, não pelo botão de merge. Isso não é motivo para enviar patches em outro lugar — abra a issue ou o PR aqui, é o endereço que é lido.

Licença

MIT. Dados servidos pela API carregam termos de redistribuição por fonte — veja https://pokemontcgapi.com/legal/attribution.