gs1br
mcp-gs1br
GS1 Brasil — Verified by GS1 API를 위한 Model Context Protocol (MCP) 서버입니다.
GTIN(EAN-8, UPC-A, EAN-13, ITF-14)으로 제품의 공식 데이터를 조회합니다: 브랜드, 설명, GPC, NCM, CEST, 이미지, 무게, 치수, 라이선스 보유자. 국가 데이터베이스(Cadastro Nacional de Produtos – CNP)와 국제 데이터베이스(GS1 Registry Platform)를 포함합니다.
사전 요구 사항
GS1 Brasil 회원이어야 합니다.
https://verifiedbygs1.gs1br.org/에서 이용 약관에 동의해야 합니다.
https://fs8.formsite.com/gsurvey/cfw75k23hq/index에서 접근 권한을 요청해야 합니다.
GS1 Brasil로부터
client_id및client_secret을 받아야 합니다.
이후 CNP / Verified by GS1 포털의 동일한 username/password를 OAuth 자격 증명으로 사용합니다.
Related MCP server: chestnyznak-mcp
설치
cd mcp-gs1br
npm install
npm run build구성
자격 증명을 환경 변수로 내보내세요:
변수 | 필수 | 설명 |
| 예 | GS1 Brasil에서 받은 Client ID |
| 예 | GS1 Brasil에서 받은 Client Secret |
| 예 | CNP / Verified by GS1 사용자 이메일 |
| 예 | 해당 사용자의 비밀번호 |
| 아니요 |
|
Claude Code에 MCP로 등록
.claude/mcp.json 또는 이에 상응하는 파일:
{
"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
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": "..." }
}
}
}제공되는 도구
gs1_validate_check_digit
GTIN의 체크 디지트(모듈로 10)를 로컬에서 검증합니다. API를 호출하지 않습니다. 할당량을 사용하기 전에 잘못된 판독값을 걸러내는 데 유용합니다.
{ "gtin": "7898357416086" }gs1_verify_gtin
GTIN을 조회하고 정규화된 요약을 반환합니다:
{
"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": { ... }
}계약한 조회 프로필(Verificação, Verificação + Nacional, Verificação + Internacional, Nacional + Internacional)에 따라 필드는 비어 있을 수 있습니다.
gs1_verify_gtin_raw
위와 동일하지만 GS1 API의 원시 JSON(배열: dadosInternacionais, dadosNacionais, verificacao)을 반환합니다.
gs1_enrich_many
최대 25개의 GTIN 배치를 순차적으로 보강합니다. 요청을 절약하기 위해 잘못된 체크 디지트를 로컬에서 필터링합니다.
{ "gtins": ["7898357416086", "4006381333931", "..."] }내부 동작
OAuth 2.0 password grant —
POST {host}/oauth/access-token에Authorization: Basic base64(client_id:client_secret)헤더와{grant_type, username, password}JSON 본문을 사용합니다.토큰 캐시는 메모리에 저장되며 TTL 3시간(expires_in = 10800)입니다. 401/403 응답 시 자동으로 재인증합니다.
조회:
GET {host}/provider/v2/verified?gtin={GTIN}에client_id및access_token헤더를 사용합니다.호스트:
https://api.gs1br.org(프로덕션)https://api-hml.gs1br.org(스테이징)
일반적인 오류
HTTP 코드 | 상황 |
200 | 성공 |
400 | 잘못된 요청 |
403 | 리소스에 대한 권한이 없는 사용자 |
404 | GTIN을 찾을 수 없음 |
500 | GS1 내부 오류 |
GTIN이 국제 제품인 경우 payload 내부에 반환되는 비즈니스 코드(returnCode / returnCodeDescription) — 공식 R1.3 매뉴얼 참조.
참고 자료
GS1 Brasil API 포털: https://portalapi.gs1br.org/
R1.3 매뉴얼 (PDF): Manual de Uso da API Verified by GS1 R1.3
CNP 매뉴얼 (PDF): API de Cadastro e Consulta CNP v3
라이선스
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