gs1br
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
GS1-Brasil-Mitglied sein.
Nutzungsbedingungen unter https://verifiedbygs1.gs1br.org/ akzeptieren.
Zugriff unter https://fs8.formsite.com/gsurvey/cfw75k23hq/index beantragen.
Von GS1 Brasil Ihre
client_idundclient_secreterhalten.
Danach verwenden Sie denselben username/password des CNP-/Verified-by-GS1-Portals als OAuth-Anmeldedaten.
Related MCP server: chestnyznak-mcp
Installation
cd mcp-gs1br
npm install
npm run buildKonfiguration
Exportieren Sie die Anmeldedaten als Umgebungsvariablen:
Variable | Erforderlich | Beschreibung |
| ja | Von GS1 Brasil erhaltene Client-ID |
| ja | Von GS1 Brasil erhaltenes Client-Secret |
| ja | E-Mail des CNP-/Verified-by-GS1-Benutzers |
| ja | Passwort desselben Benutzers |
| nein |
|
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, HeaderAuthorization: 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 Headernclient_idundaccess_token.Hosts:
https://api.gs1br.org(Produktion)https://api-hml.gs1br.org(Homologation)
Häufige Fehler
HTTP-Code | Situation |
200 | Erfolg |
400 | Ungültige Anfrage |
403 | Benutzer ohne Berechtigung für die Ressource |
404 | GTIN nicht gefunden |
500 | Interner GS1-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.
Available Tools
4 toolsgs1_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Bulk CNPJ lookup and enrichment with official Brazilian company registry data.
Bling ERP (SMB and e-commerce management, by Locaweb) via the official v3 API, sales orders, product
Manage products, EU Digital Product Passports, operator parties, and GS1 EPCIS supply-chain events.
Barcodes, price watch, QR, VINs, tariffs, invoices, VAT and product checksums, via Apify.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables querying Open Food Facts product database by barcode, full-text search, category, brand, or country.76 npmMIT
- AlicenseAqualityBmaintenanceEnables Russian product marking verification via Chestny ZNAK/CRPT APIs, including authenticity checks, product details, batch checks, and authorized GTIN/CIS lookups.556 npm6MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying products and stock, sales orders, contacts, invoices, payables/receivables, and creating contacts through the official ERP API.MIT

apipj MCP serverofficial
AlicenseNot gradedqualityCmaintenanceEnables 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