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)、ボディ 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 を参照してください。

参照

ライセンス

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