Skip to main content
Glama

mcp-gs1br

Servidor de Model Context Protocol (MCP) para la API GS1 Brasil — Verified by GS1.

Consulta datos autoritativos de productos a partir del GTIN (EAN-8, UPC-A, EAN-13, ITF-14): marca, descripción, GPC, NCM, CEST, imágenes, peso, dimensiones, licenciado. Cubre la base nacional (Cadastro Nacional de Produtos – CNP) y la base internacional (GS1 Registry Platform).

Requisitos previos

  1. Ser asociado de GS1 Brasil.

  2. Aceptar los términos de uso en https://verifiedbygs1.gs1br.org/.

  3. Solicitar la liberación de acceso en https://fs8.formsite.com/gsurvey/cfw75k23hq/index.

  4. Recibir de GS1 Brasil su client_id y client_secret.

Después de eso, usa el mismo username/password del portal CNP / Verified by GS1 como credenciales OAuth.

Related MCP server: chestnyznak-mcp

Instalación

cd mcp-gs1br
npm install
npm run build

Configuración

Exporta las credenciales como variables de entorno:

Variable

Obligatoria

Descripción

GS1BR_CLIENT_ID

sí

Client ID recibido de GS1 Brasil

GS1BR_CLIENT_SECRET

sí

Client Secret recibido de GS1 Brasil

GS1BR_USERNAME

sí

Correo electrónico del usuario CNP / Verified by GS1

GS1BR_PASSWORD

sí

Contraseña del mismo usuario

GS1BR_ENV

no

production (predeterminado) o homologacao

Registrar como MCP en Claude Code

.claude/mcp.json o equivalente:

{
  "mcpServers": {
    "gs1br": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-gs1br/dist/index.js"],
      "env": {
        "GS1BR_CLIENT_ID": "...",
        "GS1BR_CLIENT_SECRET": "...",
        "GS1BR_USERNAME": "seu@email",
        "GS1BR_PASSWORD": "...",
        "GS1BR_ENV": "production"
      }
    }
  }
}

Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "gs1br": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-gs1br/dist/index.js"],
      "env": { "GS1BR_CLIENT_ID": "...", "GS1BR_CLIENT_SECRET": "...", "GS1BR_USERNAME": "...", "GS1BR_PASSWORD": "..." }
    }
  }
}

Herramientas expuestas

gs1_validate_check_digit

Valida localmente el dígito verificador (módulo 10) de un GTIN. No consume la API. Útil para filtrar lecturas defectuosas antes de gastar cuota.

{ "gtin": "7898357416086" }

gs1_verify_gtin

Consulta un GTIN y devuelve un resumen normalizado:

{
  "gtin": "7898357416086",
  "found": true,
  "source": "national",
  "status": "Válido",
  "brand": "GS1 Brasil",
  "description": "GS1 Brasil Tênis de Corrida Style Azul com Branco Tamanho 37",
  "gpcCategoryCode": "10001070",
  "gpcCategoryName": "Calçados Esportivos - Uso Geral",
  "ncm": "0000.00.00",
  "cest": "28.059.00",
  "imageUrls": ["https://cnp30blob.blob.core.windows.net/cnp3files/..."],
  "grossWeight": { "value": 2.8, "unitCode": "KGM" },
  "netWeight":   { "value": 2.8, "unitCode": "KGM" },
  "netContent":  { "value": 1,   "unitCode": "EA"  },
  "dimensions": {
    "height": { "value": 40, "unitCode": "CMT" },
    "width":  { "value": 17, "unitCode": "CMT" },
    "depth":  { "value": 10, "unitCode": "CMT" }
  },
  "licensee": {
    "name": "GS1 BRASIL - ASSOCIACAO BRASILEIRA DE AUTOMACAO",
    "licenseType": "GCP",
    "managingOrganization": "GS1 Brasil"
  },
  "syncInformationCCG": true,
  "raw": { ... }
}

Los campos pueden venir vacíos dependiendo del perfil de consulta contratado (Verificación, Verificación + Nacional, Verificación + Internacional, Nacional + Internacional).

gs1_verify_gtin_raw

Igual que el anterior, pero devuelve el JSON crudo de la API GS1 (array con dadosInternacionais, dadosNacionais, verificacao).

gs1_enrich_many

Enriquece un lote de hasta 25 GTINs secuencialmente. Filtra localmente dígitos verificadores inválidos para ahorrar requests.

{ "gtins": ["7898357416086", "4006381333931", "..."] }

Entre bastidores

  • OAuth 2.0 password grant contra POST {host}/oauth/access-token, header Authorization: Basic base64(client_id:client_secret), body JSON {grant_type, username, password}.

  • Token cache en memoria, TTL 3h (expires_in = 10800). Reautenticación automática en 401/403.

  • Consulta: GET {host}/provider/v2/verified?gtin={GTIN} con headers client_id y access_token.

  • Hosts:

    • https://api.gs1br.org (producción)

    • https://api-hml.gs1br.org (homologación)

Errores comunes

Código HTTP

Situación

200

Éxito

400

Solicitud inválida

403

Usuario sin autorización para el recurso

404

GTIN no encontrado

500

Error interno de GS1

Códigos de negocio (returnCode / returnCodeDescription) devueltos dentro del payload cuando el GTIN es internacional — véase el manual oficial R1.3.

Referencias

Licencia

MIT.

Available Tools

4 tools
gs1_enrich_manyA

Consulta um lote pequeno de GTINs sequencialmente e retorna os dados normalizados de cada um. Valida dígito verificador localmente antes de chamar a API (economiza requests). Limitado a 25 GTINs por chamada para proteger contra rate limit da GS1.

Inputs: gtins (required), environment, skipInvalidCheckDigit.

gs1_validate_check_digitA

Valida localmente o dígito verificador (módulo 10) de um GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13) ou GTIN-14 (ITF-14). Não requer credenciais e não faz chamada HTTP. Útil para filtrar códigos com erro de leitura antes de consultar a API.

Inputs: gtin (required).

gs1_verify_gtinA

Consulta um GTIN na API Verified by GS1 (GS1 Brasil) e retorna um resumo normalizado: marca, descrição, GPC, NCM, CEST, imagens, peso, dimensões, licenciado. Requer credenciais GS1BR_* em variáveis de ambiente. Para a estrutura crua, use gs1_verify_gtin_raw.

Inputs: gtin (required), environment.

gs1_verify_gtin_rawA

Consulta um GTIN na API Verified by GS1 e retorna o payload JSON cru, exatamente como recebido da GS1 Brasil (array com 'dadosInternacionais', 'dadosNacionais' e 'verificacao'). Útil quando o consumidor precisa de campos não expostos por gs1_verify_gtin.

Inputs: gtin (required), environment.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: check digit validation, single normalized lookup, single raw lookup, and batch normalized lookup. The descriptions explicitly differentiate raw vs normalized and single vs batch, leaving no ambiguity.

    Naming Consistency5/5

    All tools follow the consistent pattern gs1_ + verb + noun/modifier (validate_check_digit, verify_gtin, verify_gtin_raw, enrich_many). The verb is always lowercase and the object is clearly descriptive, with only minor variation like 'raw' and 'many' as modifiers.

    Tool Count5/5

    Four tools is well-scoped for a GTIN validation and lookup server. It covers the essential operations without bloat, staying within the ideal range of 3–15 tools.

    Completeness5/5

    The server covers the full lifecycle of what an agent needs: local check digit validation, single lookup (both normalized and raw), and batch lookup. There are no dead ends—users can validate, query individually, and enrich in bulk.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying Open Food Facts product database by barcode, full-text search, category, brand, or country.
      76 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying products and stock, sales orders, contacts, invoices, payables/receivables, and creating contacts through the official ERP API.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables lookup and validation of Brazilian companies by CNPJ, returning registration status, address, CNAE activities, Simples Nacional/MEI status, and partners from monthly Receita Federal open data, plus validation of numeric or alphanumeric CNPJ check digits and search of active companies by activity and municipality.
      MIT