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)、ボディ 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(ホモロゲーション)
一般的なエラー
HTTPコード | 状況 |
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