mcp-gs1br

Model Context Protocol (MCP)-Server für die GS1 Brasil – Verified by GS1-API.

Ruft autoritative Produktdaten anhand der GTIN (EAN-8, UPC-A, EAN-13, ITF-14) ab: Marke, Beschreibung, GPC, NCM, CEST, Bilder, Gewicht, Maße, Lizenznehmer. Abgedeckt werden die nationale Basis (Cadastro Nacional de Produtos – CNP) und die internationale Basis (GS1 Registry Platform).

Voraussetzungen

1. GS1-Brasil-Mitglied sein.

2. Nutzungsbedingungen unter https://verifiedbygs1.gs1br.org/ akzeptieren.

3. Zugriff unter https://fs8.formsite.com/gsurvey/cfw75k23hq/index beantragen.

4. Von GS1 Brasil Ihre client_id und client_secret erhalten.

Danach verwenden Sie denselben username/password des CNP-/Verified-by-GS1-Portals als OAuth-Anmeldedaten.

Installation

cd mcp-gs1br
npm install
npm run build

Konfiguration

Exportieren Sie die Anmeldedaten als Umgebungsvariablen:

Als MCP in Claude Code registrieren

.claude/mcp.json oder Äquivalent:

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

In der 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": "..." }
    }
  }
}

Verfügbare Tools

gs1_validate_check_digit

Validiert lokal die Prüfziffer (Modulo 10) einer GTIN. Verbraucht keine API. Nützlich, um fehlerhafte Scans zu filtern, bevor Kontingent verbraucht wird.

{ "gtin": "7898357416086" }

gs1_verify_gtin

Fragt eine GTIN ab und gibt eine normalisierte Zusammenfassung zurück:

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

Felder können je nach gebuchtem Abfrageprofil leer sein (Verifizierung, Verifizierung + National, Verifizierung + International, National + International).

gs1_verify_gtin_raw

Wie oben, gibt aber das rohe JSON der GS1-API zurück (Array mit dadosInternacionais, dadosNacionais, verificacao).

gs1_enrich_many

Reichert einen Stapel von bis zu 25 GTINs sequenziell an. Filtert lokal ungültige Prüfziffern, um Requests zu sparen.

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

Hinter den Kulissen

• OAuth-2.0-Password-Grant gegen POST {host}/oauth/access-token, Header Authorization: Basic base64(client_id:client_secret), Body JSON {grant_type, username, password}.

• Token-Cache im Speicher, TTL 3h (expires_in = 10800). Automatische Reauthentifizierung bei 401/403.

• Abfrage: GET {host}/provider/v2/verified?gtin={GTIN} mit Headern client_id und access_token.

• Hosts:

  • https://api.gs1br.org (Produktion)

  • https://api-hml.gs1br.org (Homologation)

Häufige Fehler

Geschäftscodes (returnCode / returnCodeDescription), die im Payload zurückgegeben werden, wenn die GTIN international ist – siehe offizielles Handbuch R1.3.

Referenzen

• Portal API GS1 Brasil: https://portalapi.gs1br.org/

• Handbuch R1.3 (PDF): Handbuch zur Nutzung der API Verified by GS1 R1.3

• CNP-Handbuch (PDF): API für Registrierung und Abfrage CNP v3

Lizenz

MIT.