openfoodfacts-mcp-server

---

概要

Open Food Facts のパッケージ食品データを利用できます。Open Food Facts は、300 万点以上の商品を収録したクラウドソーシング型データベースです。バーコードで商品を検索したり、テキスト、タグ、アレルゲン、栄養素のしきい値で検索したり、商品を横並びで比較したり、日常的な用語をフィルターで使える標準タグに対応付けたりできます。

ツール

ツール	説明
off_get_product	バーコードで商品を 1 点取得します。原材料、アレルゲンと微量混入物、添加物、スコア、栄養情報、タグを確認できます
off_search_products	テキスト、タグフィルター、アレルゲン除外、栄養素のしきい値で検索します（100 g あたり、液体は 100 ml あたり）。バーコードを含む概要行を返します
off_compare_products	1 回の呼び出しにつき最大 10 点の商品をバーコードで比較します。栄養情報（100 g あたり、液体は 100 ml あたり）、Nutri-Score、NOVA、Green-Score を比較します
off_browse_taxonomy	人が使う用語を、off_search_products のフィルターで使う標準タグ ID に対応付けます

機能リファレンス

off_get_product _ツール

• barcode は数字のみで、先頭のゼロを除いて 4～40 桁です。省略可能な fields を指定するとレスポンスを絞り込み、フィールドが依存するデータも取得します（nutriments を指定するとサービングサイズも含まれます）。取得した項目は requested_fields に反映されます
• 原材料（生テキストと、percent_estimate を含む最大 3 階層の解析済みツリー）、allergens_tags、traces_tags、additives_tags、ingredients_analysis_tags（ヴィーガン、ベジタリアン、パーム油に関する判定）、nutriscore_grade、nova_group、ecoscore_grade（Green-Score）、nutriments（1 食分あたり、および 100 g あたり、液体の場合は 100 ml あたり）、カテゴリ／ラベル／包装／原産地／国のタグ、image_url、completeness（0～1）を返します
• traces_tags: ["en:none"] は、ラベルにアレルゲン混入の可能性がないと記載されていることを意味します。空の配列は、まだ情報が入力されていないことを意味します。どの投稿者も記録していないバーコードは not_found で失敗します

---

off_search_products _ツール

• query（最大 24 語。すべてが商品名、一般名、カテゴリ、ラベル、またはブランドに一致する必要があります。句読点は単語の区切りとして扱われるため、milk-chocolate では両方の語が必要です）と、タグフィルター categories_tag、brands_tag、labels_tag（最大 10 個）、allergens_tag、traces_tag、ingredients_analysis_tag、additives_tag、nutrition_grade、nova_group、countries_tag、exclude_allergens／exclude_traces のリスト（それぞれ最大 14 個）、および nutrient_filters（最大 18 個。100 g あたり、液体の場合は 100 ml あたり）を組み合わせて使用します。すべて AND 条件で適用されます。sort_by は省略可能です
• page_size のデフォルトは 20 で、1 回の呼び出しで最大 50 件が返されます。より大きな値（最大 10,000）を指定しても 50 件が返され、page_size_capped が設定されます。page は 50 件単位のページ数です。各行には barcode、product_name、brands、nutriscore_grade、nova_group、ecoscore_grade、categories_tags に加えて、total、total_is_lower_bound、last_page、omitted、truncated（このページ以降にも一致する商品があることを示します）が含まれます。除外条件では、アレルゲン情報が入力されていない商品も条件を通過するため、exclusion_coverage が追加されます。nutrient_filters では indexed_nutriments（フィルターの照合に使われたインデックス値。off_get_product の値と異なる場合があります）が追加されます
• query または nutrient_filters を使った検索では、最新データベースより更新が遅れるテキストインデックスが検索対象となり（text_index_snapshot に示されます）、結果の先頭 10,000 件までが対象です。また、additives_tag は additives_filter_needs_tag_search として拒否されます。タグのみの検索では、10 ページ目までライブデータベースが参照されます。いずれかの上限を超えたページを指定すると、page_out_of_range で失敗します

---

off_compare_products _ツール

• barcodes は 2～100 個で、入力順に 1 行ずつ結果が返されます。重複するバーコードは 1 回だけ比較され、異なるバーコードのうち 10 個を超えるものは取得されず、unprocessed に列挙されます
• 各行には found、nutriscore_grade、nova_group、ecoscore_grade、エネルギー、脂質、飽和脂肪、糖類、食塩、たんぱく質、食物繊維（100 g あたり、液体の場合は 100 ml あたり）、および completeness が含まれます。欠損値は補完されず、そのまま省略されます
• 投稿者の記録がないバーコードは not_found に、取得に失敗したバーコードは failed に、それぞれ reason とともに列挙されます。失敗したバーコードの行は返されませんが、ほかのバーコードの処理が妨げられることはありません

---

off_browse_taxonomy _ツール

• facet は categories、labels、allergens、additives、countries、nova_groups、nutrition_grades のいずれかです。search はタグ ID、名前、または同義語の部分文字列に一致します（「shellfish」→ en:crustaceans）。limit（デフォルトは 20）では 1 回の呼び出しで最大 100 件が返されます（200 までの値を指定しても 100 件が返されます）。結果が切り詰められた場合は、一致した件数が示されます。ページ分けには対応していません
• off_search_products にそのまま渡せる id と name の tags[] を返します。nova_groups と nutrition_grades は total_in_facet とともに完全な一覧を返します
• 5 つのオープンファセットは、ライブの Open Food Facts タクソノミーを参照します。利用できない場合は、小規模なオフラインサンプルにフォールバックし、notice が返されます。search を省略すると、そのサンプルのみが返されます

特長

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

Open Food Facts 固有の機能：

• API キーは不要です。Open Food Facts の利用規約で求められる識別用の User-Agent は組み込み済みです
• エンドポイントごとにリクエスト上限が設定されています（商品は 15／分、検索は 10／分、分類体系は 10／分）。一時的な障害は最大 4 回まで再試行します
• ハイフン付きのキー（energy-kcal_100g → energy_kcal_100g）から栄養素データを正規化し、各栄養素に単位を付けた additional_100g／additional_serving マップを提供します
• タグフィルターには正規 ID（en:organic、en:no-gluten）を指定します。テキスト検索では、大文字・小文字の違いがある表記、同義語、ブランド名を先に正規化します（US → en:united-states）
• すべての項目は投稿者が入力するため、項目がない場合はまだ記録されていないことを意味します。Nutri-Score、NOVA、Green-Score は Open Food Facts 独自の算出評価で、そのまま返されます。地域によって算出式が異なる場合があることにご注意ください

エージェント向けの出力：

• 1 食分あたりの栄養情報には分母が含まれます：serving_size、serving_quantity、serving_quantity_unit。記録がない場合はその旨も示します
• 部分的な失敗を適切に処理します：off_compare_products は、解決済みの行とともに not_found および failed を返します
• 件数の上限を明示します：検索結果には total_is_lower_bound、last_page、omitted が含まれます
• 型付きエラー：それぞれに宣言済みの reason（upstream_error、upstream_timeout、upstream_rejected、rate_limited と、ツールごとの入力に関する理由）と復旧のヒントが含まれます。不完全な上流レスポンスは再試行可能な upstream_error となり、空の結果や未検出として扱われることはありません

はじめに

公開ホスト型インスタンス

公開インスタンスは https://openfoodfacts.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定の形式が異なります。

Claude Code の場合：

claude mcp add --transport http openfoodfacts-mcp-server https://openfoodfacts.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "streamableHttp",
      "url": "https://openfoodfacts.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "url": "https://openfoodfacts.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Customize → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

API キーは不要です。MCP クライアントの設定ファイルに以下を追加します。

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openfoodfacts-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openfoodfacts-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します：

{
  "mcpServers": {
    "openfoodfacts-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/openfoodfacts-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降、または Node.js v24 以降。
• API キーやアカウントは不要です。Open Food Facts はクライアントに識別情報の提示を求めますが、サーバーが User-Agent で設定なしに提示します。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/openfoodfacts-mcp-server.git

2. ディレクトリに移動します：

cd openfoodfacts-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env if you need to override rate limits or the base URL

設定

変数	説明	デフォルト
OFF_BASE_URL	Open Food Facts API のベース URL です。	https://world.openfoodfacts.org
OFF_RATE_LIMIT_PRODUCT	商品読み取りの予算（リクエスト/分）です。デフォルトは Open Food Facts が公開している IP ごとの上限です。共有の外部 IP を使用する場合は、より低い値にしてください。	15
OFF_RATE_LIMIT_SEARCH	検索の予算（リクエスト/分）です。デフォルトは Open Food Facts が公開している IP ごとの上限です。	10
OFF_RATE_LIMIT_TAXONOMY	分類の検索予算（リクエスト/分）です。off_browse_taxonomy、テキスト検索でのタグの正規化、除外チェックで共有されます。	10
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_AUTH_MODE	認証モードです。none、jwt、oauth のいずれかを指定します。	none
MCP_LOG_LEVEL	ログレベルです（debug、info、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果を、キー名に基づいて機密情報を伏せ、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルト 16384）を上限としてログに記録します。自由形式の値に含まれる秘密情報は伏せられません。	false
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false

省略可能なオーバーライドの全リストについては、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t openfoodfacts-mcp-server .
docker run --rm -p 3010:3010 openfoodfacts-mcp-server

Dockerfile は、HTTP トランスポート、ステートレスセッションモード、および /var/log/openfoodfacts-mcp-server へのログ出力をデフォルトで使用します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/services/openfoodfacts	Open Food Facts API クライアントです。HTTP、レート制限、再試行、フィールドの正規化を扱います。
src/services/taxonomy	タグの語彙です。ライブでの解決、オフラインサンプル、タグ値の正規化を扱います。
src/utils	テキスト出力内の投稿者入力値を Markdown 用にエスケープします。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。概要は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください。
• 新しいツールは、src/mcp-server/tools/definitions/index.ts のバレル経由で登録してください。
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返してください。不足しているフィールドを捏造しないでください。

コントリビューション

Issue を歓迎します。フォームと、対応可能な報告に必要な内容については、CONTRIBUTING.md を参照してください。脆弱性は非公開の報告窓口から報告し、公開 Issue には投稿しないでください。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。Open Food Facts のデータは Open Database License (ODbL) 1.0 の下で公開されています。下流で利用する場合は、Open Food Facts を引用する必要があります。