Mealie MCP Server

mealie-mcp

Mealie向けのModel Context Protocol（MCP）サーバーです。Mealieはセルフホスト可能なレシピ管理・献立計画ツールです。

Claude Code、Claude Desktop、CodexなどのMCPクライアントから、レシピコレクションを操作できます。材料や手順を含むレシピの検索・閲覧、Webサイトからの新規レシピのインポート、タグやカテゴリの整理、献立の計画、計画に基づく買い物リストの作成、実際に調理した内容の記録が可能です。

53個のツールは上限であり、最低数ではありません。MEALIE_ALLOW_TOOLS=essentialを設定すると、厳選された8個だけが登録されます。モデルは54個から選ぶよりも、8個からのほうが適切なツールをはるかに確実に選べます。詳しくは読み込むツールの選択をご覧ください。

MealieのREST APIには、175個のパスにまたがる259個の操作があります。このサーバーが公開するのは54個のツールです。一般的なタスクは1回の呼び出しで完了し、危険な機能には一切アクセスできないように選定されています。Mealie v3.28.0で検証済みです。すべてのリクエスト形式の正確な情報源は、公開ドキュメントではなく、稼働中のインスタンスのGET /openapi.jsonです。公開ドキュメントは複数箇所で古くなっています。

特長

259個のAPI操作から厳選した53個のツール。 MealieのREST APIは、モデルが利用するには非常に広範です。ここにあるツールは、検索、レシピの閲覧やインポート、タグやカテゴリの整理、献立の計画、買い物リストの作成、料理本や評価の管理など、一般的なタスクを1回の呼び出しで行えるようにしています。

update_recipeはPUTではなくPATCHを使用します。 Mealieの置換ルートは、送信されなかったレシピのフィールドを暗黙に削除します。このツールでは、指定したフィールドだけが変更されます。

危険な機能にはアクセスできません。 トークンが許可する内容にかかわらず、管理者ルート、トークンの発行、Webhook、外部HTTPを呼び出すトリガーは利用できません。

要件

• Node.js 22以降
• Mealieインスタンスと、Settings → API Tokensから取得したAPIトークン

設定

変数	必須	説明
MEALIE_URL	はい	ベース URL。例：https://mealie.example.com
MEALIE_API_TOKEN	はい	Settings → API Tokens から取得したトークンです。作成したユーザーとして動作します。
MEALIE_READ_ONLY	いいえ	true の場合に限り、読み取り専用ツール 18 個のみを登録します
MEALIE_ACCEPT_LANGUAGE	いいえ	例：de-DE。単位名とラベル名をローカライズします
MEALIE_INSECURE_TLS	いいえ	true の場合に限り、自己署名証明書を許可します。この接続のみに適用されます
MEALIE_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* のプレフィックス、または厳選されたプリセットを指定する essential
MEALIE_DENY_TOOLS	いいえ	同じ構文を使用します。MEALIE_ALLOW_TOOLS で残った項目から除外します
ELICITATION	いいえ	false の場合、承認ダイアログを 2 回呼び出すトークンに置き換えます。プレフィックスは付きません

2 つのブール値は文字列 true と完全一致するかどうかで判定されるため、入力ミスがあると 無効のままになります。stderr の起動時の行で、現在のモードを確認してください。

トークンは読み取り後にプロセス環境から削除されるため、子プロセスが /proc/<pid>/environ から取得することはできません。

読み込むツールの選択

MEALIE_ALLOW_TOOLS と MEALIE_DENY_TOOLS には、カンマ区切りのツール名を指定します。 末尾の * はファミリー全体に一致します。essential は、次の 8 個を厳選したプリセットです。 search_recipes、get_recipe、import_recipe_from_url、create_recipe、get_todays_meals、create_mealplan_entry、list_shopping_lists、add_recipe_to_shopping_list。

MEALIE_ALLOW_TOOLS=essential
MEALIE_ALLOW_TOOLS=search_recipes,get_recipe,import_recipe_from_url
MEALIE_DENY_TOOLS=delete_*

どのツールにも一致しない項目があると、その項目を示して起動を中止します。そのため、入力ミスによって ツールが黙って隠れることはありません。存在しないツールについて、誰かが環境変数をたどって原因を調べることはないからです。フィルターされたツールは登録されないため、tools/list にも表示されず、 tools/call でも未知のツールとなります。これは MEALIE_READ_ONLY によって書き込みツールが 登録されない場合と同じです。

このサーバーを複数同時に実行する場合は、mcp-hub がもう 1 つの選択肢です。 その /hub エンドポイントは、すべてのサーバーのツールを 6 つのメタツールに置き換えます。

インストール

Claude Code

claude mcp add mealie \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  -- npx -y @ni-c/mealie-mcp

Claude Desktop

同じ設定項目は、JSON 設定を受け付ける任意の MCP クライアントで使用できます。

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": {
        "MEALIE_URL": "https://mealie.example.com",
        "MEALIE_API_TOKEN": "…"
      }
    }
  }
}

Codex

~/.codex/config.toml：

[mcp_servers.mealie]
command = "npx"
args = ["-y", "@ni-c/mealie-mcp"]

[mcp_servers.mealie.env]
MEALIE_URL = "https://mealie.example.com"
MEALIE_API_TOKEN = "…"

MCP Inspector

ツールを対話形式で試すには：

npx @modelcontextprotocol/inspector npx -y @ni-c/mealie-mcp

Docker

docker run --rm -i \
  -e MEALIE_URL=https://mealie.example.com \
  -e MEALIE_API_TOKEN=… \
  ghcr.io/ni-c/mealie-mcp

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクタ、Claude on the web、 Cursor、LibreChat など）からは、mcp-hub を経由して mealie-mcp に接続できます。1 つの コンテナで複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、単一のパスワードの背後に OAuth 2.1 ログインを用意します。また、OAuth を利用できないクライアント向けに長期間有効なトークンも提供します。その /hub エンドポイントでは、すべてのサーバーを 6 つのメタツールの背後に配置するため、モデルのコンテキストに N×ツールスキーマを含めずに、1 つのコネクタからすべてのサーバーに接続できます。また、両方のプロトコルリビジョンに対応しており、このサーバーが尋ねる質問は、経由先にいる人に届きます。

/config/mcp.json では Claude Code の形式を使用するため、すでに設定したエントリーをそのまま使えます。

{
  "mcpServers": {
    "mealie": {
      "command": "npx",
      "args": ["-y", "@ni-c/mealie-mcp"],
      "env": { "MEALIE_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

ここでの allowTools と denyTools は、ハブ独自のサーバーごとのフィルターであり、env の *_ALLOW_TOOLS とは異なります。その違いと、起こりがちな設定ミスについては、 クライアントガイドをご覧ください。

ツール

すべてのツールは outputSchema を宣言し、テキストブロックと併せて structuredContent を返すため、クライアントは文章を解析せずに結果を利用できます。 文 — "Deleted the recipe with id …" — だけを返していた9つのツールも、現在はフィールドも返します。

ほとんどのツールには、フィールドとして untrusted: true と source: "mealie" が含まれます。レシピは任意のウェブサイトから頻繁にスクレイピングされ、コメントはそのインスタンスの他のユーザーによって投稿されるためです。このフィールドがない11のツールは、このサーバーに渡されたIDを返します。ただし get_about は例外で、バージョン文字列と、認証に使われたアカウントの権限フラグを返します。これらはモデルが事実として扱うべき情報です。

Mealie のレコードは、このサーバーが構築する最上位キーを持つオープンオブジェクトとして記述されています。セルフホスト可能な Mealie はどのリリースでも利用でき、SDK は結果を返す前にそれぞれのスキーマに照らして検証します。厳密な構造にすると、リリースで追加されたフィールドによってツール全体が失敗するようになってしまいます。

レシピ — search_recipes、get_recipe、suggest_recipes、create_recipe、 update_recipe、parse_recipe_ingredients、duplicate_recipe、set_recipe_image、set_recipe_last_made、 delete_recipe 🔒

インポート — preview_recipe_url（ドライラン、保存なし）、import_recipe_from_url、 import_recipe_from_html_or_json、import_recipe_from_image

整理 — list_organizers、create_organizer、update_organizer、 delete_organizer 🔒 — 各ツールは kind: tag | category | tool を受け取ります

食材 — list_foods、create_food、merge_foods 🔒、list_units、 create_unit、merge_units 🔒、parse_ingredients

献立計画 — list_mealplans、get_todays_meals、create_mealplan_entry、 create_random_meal、update_mealplan_entry、delete_mealplan_entry 🔒

買い物 — list_shopping_lists、get_shopping_list、create_shopping_list、 delete_shopping_list 🔒、add_shopping_list_items、update_shopping_list_items、 delete_shopping_list_items 🔒、add_recipe_to_shopping_list、 remove_recipe_from_shopping_list

料理本 — list_cookbooks、get_cookbook、create_cookbook、 delete_cookbook 🔒

メモと共有 — set_recipe_rating、add_recipe_comment、 delete_recipe_comment 🔒、list_recipe_comments、list_recipe_timeline、 create_timeline_event、list_share_tokens、create_share_token 🔒、 delete_share_token 🔒

インスタンス — get_about

🔒 は、MCP elicitation（モデルが本人に代わって応答できないダイアログ）を通じて人に確認を求めます。クライアントでダイアログを表示できない場合は、2回の呼び出しを行う confirm_token にフォールバックします。詳しくは 本人への確認を参照してください。

レシピはどこでもスラッグまたは UUID で指定できます。Mealie は識別子の領域をこの2つに分けており、ツールは渡された方を解決します。

意図的に公開していないもの

/api/admin 以下のすべて（バックアップ、復元、メンテナンス、ユーザー、グループ、世帯の管理、メール、AI プロバイダーの設定）、/api/users/api-tokens（API 認証情報を生成するツールは権限昇格につながる可能性があります）、認証ルート、ユーザー CRUD とパスワード、ウェブフック、イベント通知、レシピアクション（3つすべて、インスタンスから外部への HTTP 通信を発生させます）、献立計画ルール、マイグレーション、シーダー、招待、一括エクスポートと ZIP ダウンロード、アセットのアップロードは公開していません。公開している唯一のアップロードルートは、set_recipe_image を通じたレシピのカバー画像です。

PUT /api/recipes/{slug} も公開していません。このエンドポイントは33フィールドからなるレシピオブジェクト全体を置き換えるため、部分更新に使うと食材、手順、タグが気づかないうちに削除されます。update_recipe は PATCH を使います。

安全性

• インスタンスのコンテンツは信頼できない入力です。 レシピは任意のウェブサイトから定期的にスクレイピングされ、コメントは他のユーザーから投稿されるため、インスタンスのコンテンツを含む可能性があるすべてのツール結果には、モデルにデータとして扱うよう明示するマーカーが付与されます。これはインポート後も重要です。テキストはデータベースに残り、get_recipe を通じて再び返されます。
• インポートツールでは、このサーバーではなく Mealie が取得を行います。 URL は http／https に制限され、ループバックホストとリンクローカルホストは拒否されます。クラウドのメタデータエンドポイントと、それらに解決されるホスト名も対象です。アドレスは数値で比較されるため、[::ffff:169.254.169.254] のような IPv4 マップ形式のリテラルも検出されます。また、ホスト名も名前解決されます。ただし、ここで名前解決できない名前はそのまま渡されるため、ベストエフォートです。0.1.2 以降、プライベート LAN アドレスはそのまま渡されますが、Mealie 自体が拒否するため、ここではなく Mealie 側でインポートが失敗します。import_recipe_from_html_or_json を含め、このチェックの対象外となる内容については SECURITY.md を参照してください。
• 確認プロンプトに上流のテキストは引用されません。含まれるのは ID、件数、フラグのみです。
• レスポンスには上限があります。大きすぎる結果は JSON の途中で切らずに項目全体を除外し、レスポンス本文の読み込みは 8 MB を超えません。
• リダイレクトは拒否されるため、トークンが別のホストに再送信されることはありません。

信頼モデルと脆弱性の報告方法については、SECURITY.md を参照してください。

ドキュメント

完全なガイド、ツールリファレンス、セキュリティに関する注意事項は mealie-mcp.ni-c.de にあります（ソースは docs/ にあります）。

開発

npm install && npm test && npm run build

npm run test:integration では、Docker 上の使い捨て Mealie インスタンスに対してカタログ内のすべてのツールをテストします。インスタンスの起動方法は CONTRIBUTING.md にあります。

アーキテクチャ図とソーシャルカードは、npm run assets により docs/assets/architecture.source.svg と docs/assets/og.json から生成されます。生成済みファイルが手動で編集されていると、CI は失敗します。

リリース

すべてタグによって実行され、手動で公開する手順はありません。

1. CHANGELOG.md の [Unreleased] セクションを新しいバージョンに変更し、日付を記入します。リリースワークフローでは awk でこのセクションを抽出するため、## [x.y.z] という見出し形式が重要です。

2. package.json の version を更新します。

3. npm run lint && npm run build && npm run test:coverage を実行します。

4. コミットした後、署名付きの注釈付きタグを作成します。

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1
   

その後 release.yml が、タグと package.json のバージョンが一致することを検証し、Trusted Publishing（OIDC — 漏えいする npm トークンはありません）を使用して来歴情報とともに npm に公開します。さらに、server.json の両方のパッケージエントリにバージョンを同期し、MCP レジストリに公開して、変更履歴のセクションから GitHub リリースを作成します。ci.yml は並行して、マルチアーキテクチャのコンテナイメージを GHCR にプッシュします。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。脆弱性については公開 Issue ではなく、非公開の報告方法をご利用ください。方針は SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel