gs1br
mcp-gs1br
Model Context Protocol (MCP) server для API GS1 Brasil — Verified by GS1.
Предоставляет авторитетные данные о товарах по 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.
После этого используйте те же username/password от портала CNP / Verified by GS1 в качестве учётных данных OAuth.
Related MCP server: chestnyznak-mcp
Установка
cd mcp-gs1br
npm install
npm run buildКонфигурация
Экспортируйте учётные данные как переменные окружения:
Переменная | Обязательная | Описание |
| да | Client ID, полученный от GS1 Brasil |
| да | Client Secret, полученный от GS1 Brasil |
| да | Эл. почта пользователя CNP / Verified by GS1 |
| да | Пароль того же пользователя |
| нет |
|
Регистрация в качестве MCP в Claude Code
.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
Локально проверяет контрольную цифру (модуль 10) GTIN. Не обращается к 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
То же, что и выше, но возвращает сырой JSON API GS1 (массив с 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 |
Бизнес-коды (returnCode / returnCodeDescription) возвращаются внутри payload, когда GTIN является международным — см. официальное руководство R1.3.
Ссылки
Портал API GS1 Brasil: https://portalapi.gs1br.org/
Руководство R1.3 (PDF): Руководство по использованию API Verified by GS1 R1.3
Руководство CNP (PDF): API регистрации и запроса 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