Skip to main content
Glama

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)를 포함합니다.

사전 요구 사항

  1. GS1 Brasil 회원이어야 합니다.

  2. https://verifiedbygs1.gs1br.org/에서 이용 약관에 동의해야 합니다.

  3. https://fs8.formsite.com/gsurvey/cfw75k23hq/index에서 접근 권한을 요청해야 합니다.

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

구성

자격 증명을 환경 변수로 내보내세요:

변수

필수

설명

GS1BR_CLIENT_ID

예

GS1 Brasil에서 받은 Client ID

GS1BR_CLIENT_SECRET

예

GS1 Brasil에서 받은 Client Secret

GS1BR_USERNAME

예

CNP / Verified by GS1 사용자 이메일

GS1BR_PASSWORD

예

해당 사용자의 비밀번호

GS1BR_ENV

아니요

production (기본값) 또는 homologacao

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 매뉴얼 참조.

참고 자료

라이선스

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