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/ 接受使用条款。
从 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配置
将凭据导出为环境变量:
Variável | Obrigatória | Descrição |
| 是 | 从 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),请求体 JSON{grant_type, username, password}。内存中的令牌缓存,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(预发布)
常见错误
Código HTTP | Situação |
200 | 成功 |
400 | 无效请求 |
403 | 用户无权访问该资源 |
404 | 未找到 GTIN |
500 | GS1 内部错误 |
当 GTIN 为国际时,负载内返回的业务代码(returnCode / returnCodeDescription)——参见官方手册 R1.3。
参考
GS1 Brasil API 门户:https://portalapi.gs1br.org/
手册 R1.3(PDF):Verified by GS1 API 使用手册 R1.3
CNP 手册(PDF):CNP 注册与查询 API 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