Skip to main content
Glama

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).

Предварительные требования

  1. Быть ассоциированным членом GS1 Brasil.

  2. Принять условия использования по ссылке https://verifiedbygs1.gs1br.org/.

  3. Запросить предоставление доступа по ссылке https://fs8.formsite.com/gsurvey/cfw75k23hq/index.

  4. Получить от 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

Конфигурация

Экспортируйте учётные данные как переменные окружения:

Переменная

Обязательная

Описание

GS1BR_CLIENT_ID

да

Client ID, полученный от GS1 Brasil

GS1BR_CLIENT_SECRET

да

Client Secret, полученный от GS1 Brasil

GS1BR_USERNAME

да

Эл. почта пользователя CNP / Verified by GS1

GS1BR_PASSWORD

да

Пароль того же пользователя

GS1BR_ENV

нет

production (по умолчанию) или homologacao

Регистрация в качестве 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.

Ссылки

Лицензия

MIT.

Available Tools

4 tools
gs1_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

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying Open Food Facts product database by barcode, full-text search, category, brand, or country.
      76 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying products and stock, sales orders, contacts, invoices, payables/receivables, and creating contacts through the official ERP API.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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