Mealie MCP Server

Mealie MCP サーバー

AI アシスタントを、Claude Desktop などのクライアントを通じて Mealie のレシピデータベースに接続する Model Context Protocol（MCP）サーバーです。

目次

• 機能
• クイックスタート
• 設定
• リモートアクセス
• Docker
• 使用例
• 利用可能なツール
• 開発
• 重要な注意事項
• サポートと貢献
• ライセンスとクレジット

機能

• レシピ： レシピの作成、読み取り、更新、インポート、複製、削除ができます。
• 検索： テキスト、カテゴリ、タグ、ツールで、AND／OR ロジックを使って絞り込めます。
• 画像とアセット： レシピの画像やファイルをアップロードしたり、URL から画像を設定したりできます。
• 栄養情報と表示： 1 食分あたりの栄養情報や、showAssets、showNutrition などのレシピ表示設定を設定できます。
• 食材： 自由記述の食材を、Mealie の食材および単位の語彙に照合して解決できます。
• 買い物リスト： リストや項目の管理、一括操作、数量を調整したレシピ食材の追加ができます。
• 整理： カテゴリ、タグ、食材、単位、レシピのツールを管理し、未使用のカテゴリやタグを見つけられます。
• 食事計画： 食事計画のエントリーの表示、作成、更新、削除、複数エントリーの作成や、レシピを今日作ったものとしてマークできます。

クイックスタート

前提条件

• Python 3.12+
• 稼働中の Mealie インスタンスと、アカウント設定から取得した API キー
• パッケージマネージャー uv

インストール

オプション 1：MCP SDK CLI を使用する（推奨）

リポジトリをクローンし、Python MCP SDK が提供する mcp コマンドを使ってサーバーを Claude Desktop にインストールします（単体の fastmcp パッケージは不要です）。

git clone https://github.com/rldiao/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --locked
uv run mcp install src/server.py --with-editable . \
  --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  --env-var MEALIE_API_KEY=your-mealie-api-key

オプション 2：uvx を使用する

クローンせずに GitHub から直接実行するには、MCP クライアントの設定に以下を追加します（Claude Desktop では claude_desktop_config.json を使用します）。

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rldiao/mealie-mcp-server",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

サーバーを読み込むには、Claude Desktop を再起動してください。

設定

MCP クライアントの設定またはシェルで環境変数を設定します。ローカルのチェックアウトでは、.env.template を .env にコピーして、インスタンスの詳細を記入することもできます。API キーは決してコミットしないでください。

変数	デフォルト	説明
MEALIE_BASE_URL	必須	プロトコルと、必要に応じてポートを含む Mealie のベース URL
MEALIE_API_KEY	必須	Mealie のアカウント設定から取得した API キー
MEALIE_ENABLE_AI_IMPORT	false	AI によるレシピのインポートを有効化します。true／false（大文字と小文字を区別しません）を指定します
MCP_TRANSPORT	stdio	stdio、streamable-http、またはレガシーの sse
MCP_HOST	127.0.0.1	HTTP のバインドアドレス。コンテナでは 0.0.0.0 を使用します
MCP_PORT	8765	HTTP ポート。1〜65535 の範囲で指定します
LOG_LEVEL	INFO	DEBUG、INFO、WARNING、ERROR、または CRITICAL

リモートアクセス

デフォルトの stdio トランスポートはローカルのクライアント向けです。HTTP クライアントにサービスを提供するには、上記の説明に従って Mealie の認証情報を設定し、チェックアウトから実行します。

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8765
uv run mealie-mcp-server

サーバーは http://<host>:<port>/mcp に MCP エンドポイントを公開します。

セキュリティ： HTTP トランスポートには認証機能が組み込まれていません。エンドポイントにアクセスできる人は誰でも、そのツールを通じて設定済みの Mealie 認証情報を使用できます。信頼できるインターフェース上でのみ公開してください。リモートアクセスには、認証と HTTPS を強制するリバースプロキシを使用してください。

Docker

Dockerfile は、サーバーを永続的なコンテナとして実行します。

ビルド

docker build -t mealie-mcp-server .

単体実行

docker run -d \
  --name mealie-mcp \
  -e MEALIE_BASE_URL=http://your-mealie-host:9000 \
  -e MEALIE_API_KEY=your-mealie-api-key \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8765 \
  -p 127.0.0.1:8765:8765 \
  mealie-mcp-server

ポートはホストのループバックインターフェースでのみ公開されます。リモートからアクセス可能にする前に、リモートアクセスを参照してください。

Docker Compose

Mealie を実行する Compose ファイルに、このサービスを追加します。この例では、 Mealie サービスの名前を mealie とし、両方のサービスが、その Compose ファイルで定義された mealie_net というネットワークを使用することを前提としています。シェルまたは Compose の .env ファイルで MEALIE_API_KEY を設定してください。

services:
  mealie-mcp:
    build: .
    container_name: mealie-mcp
    restart: unless-stopped
    environment:
      MEALIE_BASE_URL: http://mealie:9000
      MEALIE_API_KEY: ${MEALIE_API_KEY}
      MCP_TRANSPORT: streamable-http
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8765"
    expose:
      - "8765"
    networks:
      - mealie_net

expose ではホストのポートは公開されません。リモートアクセスするには、同じネットワーク上のリバースプロキシを接続し、 HTTP セキュリティに関するガイダンスに従ってください。

使用例

"Search for chicken recipes"
"Create a new recipe for pasta carbonara"
"Mark the meatloaf recipe as made today"
"Create a shopping list for this week"
"Add all ingredients from the lasagna recipe to my shopping list"
"Plan chicken soup for lunch on Friday"

詳細なワークフローとトラブルシューティングについては、使用例を参照してください。

利用可能なツール

レシピツール（12 操作）

• get_recipes - 高度なフィルタリングを使用してレシピを一覧表示／検索します
• get_recipe - レシピの詳細全体、または concise=true の場合は概要を取得します
• create_recipe - レシピを作成します。必須なのは名前のみで、材料、手順、メタデータ、栄養情報、表示設定は任意です
• import_recipe_from_url - Web ページからレシピをインポートします
• update_recipe - 栄養情報や表示設定を含む内容またはメタデータを更新します。省略したフィールドは保持され、空のリストを指定すると内容がクリアされます
• duplicate_recipe - レシピを複製します
• mark_recipe_last_made - 最終作成日時を更新します
• set_recipe_image_from_url - URL から画像を設定します
• upload_recipe_image_file - 画像ファイルをアップロードします
• upload_recipe_asset_file - ドキュメント／アセットをアップロードします
• update_recipe_categories_and_tags - ID を使用して、カテゴリー、タグ、またはその両方を置き換えるか、クリアします
• delete_recipe - レシピを削除します

買い物リストツール（15 操作）

• get_shopping_lists - すべての買い物リストを一覧表示します
• create_shopping_list - 新しいリストを作成します
• get_shopping_list - ID でリストを取得します
• update_shopping_list - その他のフィールドを保持したままリスト名を変更します
• delete_shopping_list - リストを削除します
• add_recipe_to_shopping_list - レシピの材料を追加します
• remove_recipe_from_shopping_list - レシピの材料を削除します
• get_shopping_list_items - すべての項目を一覧表示します
• get_shopping_list_item - ID で項目を取得します
• create_shopping_list_item - 単一の項目を作成します
• create_shopping_list_items_bulk - 複数の項目を作成します
• update_shopping_list_item - 項目を更新します（フィールドは保持されます）
• update_shopping_list_items_bulk - 複数の項目を更新します
• delete_shopping_list_item - 単一の項目を削除します
• delete_shopping_list_items_bulk - 複数の項目を削除します

カテゴリーツール（6 操作）

• get_categories - カテゴリーを一覧表示／検索します
• get_empty_categories - 未使用のカテゴリーを検索します
• create_category - 新しいカテゴリーを作成します
• get_category - category_id または category_slug のいずれか一方だけを指定して取得します
• update_category - カテゴリーを更新します
• delete_category - カテゴリーを削除します

タグツール（6 操作）

• get_tags - タグを一覧表示／検索します
• get_empty_tags - 未使用のタグを検索します
• create_tag - 新しいタグを作成します
• get_tag - tag_id または tag_slug のいずれか一方だけを指定して取得します
• update_tag - タグを更新します
• delete_tag - タグを削除します

食品ツール（5 操作）

• get_foods - 食品を一覧表示／検索します（構造化された材料の ID を解決します）
• create_food - 新しい食品を作成します
• get_food - ID で取得します
• update_food - 食品を更新します
• delete_food - 食品を削除します

単位ツール（5 操作）

• get_units - 単位を一覧表示／検索します
• create_unit - 新しい単位を作成します
• get_unit - ID で取得します
• update_unit - 単位を更新します
• delete_unit - 単位を削除します

キッチンツール（5 操作）

• get_tools - レシピ用のツールを一覧表示／検索します（householdsWithTool を含みます）
• create_tool - 新しいツールを作成します
• get_tool - tool_id または tool_slug のいずれか一方だけを指定して取得します
• update_tool - ツールを更新します
• delete_tool - ツールを削除します

パーサーツール（1 操作）

• parse_ingredients - 1 回のリクエストで 1 行以上の材料を解決します。常にリストを返します

食事プランツール（6 件の操作）

• get_all_mealplans - 食事プランを一覧表示
• create_mealplan - 食事プランのエントリーを作成
• create_mealplan_bulk - 複数のエントリーを作成
• update_mealplan - 省略されたフィールドを保持したままエントリーを更新
• delete_mealplan - エントリーを削除
• get_todays_mealplan - 今日の食事を取得

合計：61 個のツール

MEALIE_ENABLE_AI_IMPORT=true にすると、import_recipe_with_ai がオプションのレシピ操作として追加されます。レシピツール 13 個を含め、合計 62 個のツールになります。無効の場合は、ツールの検出対象に含まれず、呼び出すこともできません。

統合されたツールへの移行（破壊的変更）

冗長な MCP 名はエイリアスとして残さず、削除されました。クライアントのツール一覧を更新し、保存済みの呼び出しを変更してください。

削除されたツール	置き換え先
create_recipe_full	同じ引数で create_recipe
get_recipe_detailed	get_recipe（デフォルトで全詳細を取得）
get_recipe_concise	get_recipe に concise=true を指定
patch_recipe	同じ引数で update_recipe
set_recipe_categories	category_ids を指定して update_recipe_categories_and_tags
set_recipe_tags	tag_ids を指定して update_recipe_categories_and_tags
get_category_by_slug	category_slug を指定して get_category
get_tag_by_slug	tag_slug を指定して get_tag
get_tool_by_slug	tool_slug を指定して get_tool
parse_ingredient	parse_ingredients(ingredients=[...]) を呼び出し、最初の結果を読み取る

既存の create_recipe と update_recipe の呼び出しは引き続きサポートされます。レシピの更新では、コンテンツとメタデータを組み合わせられるようになり、省略されたフィールドや null のフィールドは変更されません。材料と手順のリストでは、指定されたフィールドのみが置き換えられます。栄養情報は引き続きオブジェクト全体が置き換えられ、設定はマージされます。

個別の操作は引き続き分かれています。単一書き込みと一括書き込みでは、レスポンスと失敗時の動作が異なります。ページ分割された一覧は、個別の検索、未使用の整理項目に関するクエリ、今日の食事プランとは異なります。レシピの URL インポート、画像 URL のスクレイピング、ファイルのアップロードも、それぞれ異なる操作を行います。

AI インポート（オプション）

MCP クライアントの環境、シェル、またはローカルの .env で MEALIE_ENABLE_AI_IMPORT=true を設定します。サーバーを再起動し、クライアントのツール一覧を更新してください。これは stdio、SSE、Streamable HTTP に適用されます。オフラインの SDK による検出は設定やネットワークを必要とせず、デフォルトのツールのみを一覧表示します。オプションの登録は、実行時の起動時（または有効な ServerConfig を明示的に渡したとき）に行われます。

import_recipe_with_ai には Mealie 3.23.0+ と、API ユーザーのグループに設定されたデフォルトの AI プロバイダーが必要です。以下を任意に組み合わせて指定できます。

• content：プレーンテキスト、未加工の HTML、または JSON。修正やメモにも使用されます。
• url：HTTP(S) のレシピまたは動画の URL。Mealie が取得し、ソースとして保存します。
• image_paths：MCP サーバーのファイルシステムからアクセスできる画像パスのリスト。リモートの呼び出し元のコンピューター上のパスではありません。複数の写真から 1 つのレシピが作成され、最初の写真がカバー画像になります。

空白以外のソースを少なくとも 1 つ指定する必要があります。ソースは統合され、内容が食い違う場合は貼り付けたコンテンツが優先されます。translate_language を指定すると翻訳をリクエストできます。create_new_organizers のデフォルトは false です。一致する既存のタグ、カテゴリ、キッチンツールを割り当てることはできますが、新規作成されるのは明示的にリクエストした場合のみです。

各インポートの前に、サーバーは /api/groups/self を読み取り、aiEnabled と、写真の場合は imageProviderEnabled を確認します。機能情報の欠落や形式不備、または照会の失敗があった場合、無効であることを黙って返すのではなく、明示的なエラーを返します。動画の検出と音声プロバイダーの要件は Mealie が処理します。これらの確認で確認できるのは設定のみであり、プロバイダーへの接続、認証情報、利用可能なクォータは確認できません。

このツールはレシピをただちに作成して保存します。 ソースの素材は Mealie に設定された AI プロバイダーによって処理され、料金が発生する場合があります。返されたレシピの正確性を確認してください。インポートの読み取りタイムアウトは 300 秒です。それ以外の API 呼び出しには、既存のタイムアウトが適用されます。インポートは自動的に再試行されません。タイムアウトや接続失敗の後に再試行したり別のツールに切り替えたりする前に、Mealie を確認してください。作成がすでに成功している場合があります。後続の取得に失敗した場合、エラーには created_slug と stage が含まれます。そのレシピを取得し、再度インポートしないでください。

タスクに応じてツールを選択してください。

タスク	ツール
通常のレシピのウェブページ	import_recipe_from_url
構造化されていないテキスト、写真、動画、複数ソースの組み合わせ、翻訳、または明示的な AI インポート	import_recipe_with_ai（オプトイン）
すでに作成済みの材料と手順を保存する	create_recipe
内容を抽出せずに既存のレシピに写真を添付する	upload_recipe_image_file

オプトインの設定が制御するのは、この新しいツールのみです。URL のスクレイピングにおける Mealie 独自の AI フォールバックや、その他の既存の AI 機能は無効になりません。Mealie の AI インポートのドキュメントと使用例を参照してください。

開発

セットアップ

リポジトリをクローンした後、開発用の依存関係をインストールします。

uv sync --locked --extra dev

手動でテストするには、Mealie インスタンスを設定します。

cp .env.template .env
# Edit .env with your Mealie instance details

MCP Inspector を起動します。

uv run mcp dev src/server.py

オフラインチェックを実行します。これらには Mealie インスタンスも認証情報も必要ありません。

uv run ruff check src tests
uv run pytest -q

プロジェクト構成

パス	目的
src/mealie/	HTTP クライアントと API ミックスイン
src/tools/	FastMCP ツールの定義と登録
src/models/	Pydantic のリクエストモデルとレスポンスモデル
src/server.py	設定、ライフサイクル、エントリーポイント
src/prompts.py	MCP プロンプト
tests/	オフラインテストとフィクスチャ

リポジトリの規約は AGENTS.md に記載されています。ソースコード と テスト には、それぞれ詳細なガイダンスがあります。

自動テストスイートは偽の HTTP レスポンスを使用し、ローカル HTTP トランスポートのテストも含みます。デプロイ済みの Mealie バージョンとの互換性テストに代わるものではありません。

重要な注意事項

以下の呼び出しは、MCP ツールの引数を説明するために Python 形式で記述しています。単独で実行できる Python スクリプトではありません。

タグとカテゴリによるフィルタリング

レシピをフィルタリングする場合、表示名ではなく、スラッグまたは UUID を必ず使用してください。

まず get_tags() または get_categories() を使用して、正しいスラッグを確認します。

get_recipes(tags=["quick-meals", "healthy"])

たとえば、表示名の Quick Meals ではなく、quick-meals を渡してください。

栄養情報は結合されず、置き換えられます

Mealie は書き込み時に nutrition オブジェクト全体を置き換えます。update_recipe も同様なので、保持したい値はすべて渡してください。

# Clears every nutrition value except fat.
update_recipe(slug="...", nutrition={"fatContent": "12"})

材料を一括で解析する

材料を手動で解決するには、毎回 get_foods と get_units を 1〜2 回呼び出す必要があります。parse_ingredients はレシピ全体を 1 回のリクエストで処理し、create_recipe にそのまま渡せる結果を返します。

parse_ingredients(ingredients=["1/4 cup chopped onion", "2 large eggs"])
# -> [{"input": "1/4 cup chopped onion", "confidence": 0.99, "quantity": 0.25,
#      "unit": {"id": "...", "name": "cup"},
#      "food": {"id": "...", "name": "onion"}, "note": "chopped"}, ...]

単位または食品が null の場合、インスタンスに一致する項目がありません。create_food または create_unit で作成するか、テキストをメモに残してください。フィールドごとの信頼度を含む Mealie の完全なレスポンスを得るには、verbose=True を渡してください。

アップロードしたアセットと栄養情報は保存されても非表示になることがあります

レシピの settings オブジェクトは、UI に表示する内容を制御します。showAssets と showNutrition はアセットカードと栄養情報カードの表示を制御するため、upload_recipe_asset_file でアップロードしたアセットが API レスポンスに含まれていても、Web UI では表示されない場合があります。次のように切り替えてください。

update_recipe(slug="...", settings={"showAssets": True})

Mealie は新しいレシピの設定を、世帯の設定（recipeShowAssets、recipeShowNutrition、...）から初期化するため、デフォルト値はインスタンスごとに異なります。決めつけずに確認してください。

渡したトグルのみが変更されます。Mealie は設定の PATCH で省略されたトグルを確実に保持するとは限らないため、このツールはレシピの現在の設定を読み取り、統合したオブジェクトを送信します。

フィールドの保持

買い物リスト項目の更新では、単体更新と一括更新のどちらも現在のレコードを取得し、省略されたフィールドを保持します。変更するフィールドだけを指定してください。

# Only updates 'checked' field, preserves note, quantity, etc.
update_shopping_list_item(item_id="...", checked=True)

買い物リストの一括入力では、shopping_list_id のような snake_case 名と、shoppingListId のような Mealie の camelCase 名の両方を使用できます。一括更新でエイリアスが競合する場合や ID が重複する場合は、書き込み前に拒否されます。

ミールプランの検証とクリア

食事の日付には YYYY-MM-DD を使用し、エントリーの種類には breakfast、lunch、dinner、または side を指定してください。作成時にはレシピか、空白以外の文字を含むタイトルが必要です。一括ミールプランは、エントリーを作成する前に全件検証されます。

省略された更新フィールドは変更されません。既存のレシピへのリンクを削除するには、update_mealplan(entry_id="...", clear_recipe=True, title="Leftovers") を使用してください。clear_recipe と新しい recipe_id は同時に指定しないでください。

一部の書き込みが完了した状態からの復旧

レシピの作成・データ入力と一括ミールプランの作成には複数の API リクエストが必要であり、アトミックではありません。後続のリクエストが失敗した場合、ツールのエラーには完了した処理を特定する復旧情報が含まれます。その情報と現在の Mealie の状態を確認し、操作全体をむやみに再試行しないでください。失敗またはタイムアウトしたリクエストでも、リモート側で完了している場合があります。

サポートとコントリビューション

• 変更内容と移行に関する注意事項については、変更履歴を確認してください。
• 使用ガイドと Mealie のドキュメントを確認してください。
• 問題はGitHub のイシューから報告してください。
• プルリクエストを送る際は、開発ワークフローに従い、動作を変更する場合は テストを追加してください。

ライセンスとクレジット

MIT ライセンスのもとでライセンスされています。

• Mealie - レシピ管理システム
• Python MCP SDK - SDK と 同梱の FastMCP サーバー
• Model Context Protocol - プロトコルのドキュメント
• Claude Desktop