Better Mealie MCP

---

FastMCP の from_openapi を使って構築されています。ツールは Mealie の OpenAPI 仕様から直接生成されるため、サーバーは Mealie と同期され、手作業で保守するものはありません。ツールの全一覧は TOOLS.md をご覧ください。

💬 何ができますか？

あなたの指示	実行されること
「この URL からチキンティッカマサラのレシピを追加して」	レシピを取得してインポートします
「パントリーにある食材で何が作れる？」	手元の食材からレシピを検索します
「来週の夕食の献立を立てて」	献立の項目を作成します
「それらの食事の買い物リストを作って」	まとめて買い物リストを生成します
「スープすべてに『冬』タグを付けて」	レシピのタグを一括更新します

🧙 セットアップウィザード

→ セットアップウィザードを開く

JSON を手書きする必要はありません。ウィザードが選択肢を順に案内し、お使いの構成に合わせて、そのまま貼り付けられる設定を生成します。

• インストール — Docker イメージ、またはソースからインストールします。
• クライアント — Claude Code、Claude Desktop、Cursor、VS Code、Gemini CLI、または ChatGPT（それぞれの設定形式に対応しています）。
• 接続 — stdio または HTTP、API トークンまたはユーザー名／パスワード。
• ツールの制限 (任意) — 259 個のツールを必要なグループのみに絞り、コンテキストを軽量化したり、ツール数に上限のあるクライアントに対応したりできます。パック （料理、献立作成、共有と閲覧、管理とユーザー）から選ぶか、グループを個別に選択できます。グループの ⓘ をタップすると、その中のすべてのツールを確認できます。選択内容は MEALIE_INCLUDE_TAGS として生成される設定に反映されます。

🚀 セットアップ

Docker（GHCR イメージ）：

docker pull ghcr.io/djwmarcx/better-mealie-mcp
docker run -i --rm \
  -e MEALIE_BASE_URL=http://host.docker.internal:9925 \
  -e MEALIE_API_TOKEN=... \
  ghcr.io/djwmarcx/better-mealie-mcp            # stdio; add `--http 8000` for HTTP

イメージはリリースごとに公開され、<mealie-version> と latest のタグが付与されます。 コンテナ内では、localhost はコンテナを指します。MEALIE_BASE_URL は、 host.docker.internal（macOS/Windows）またはホストの LAN IP（Linux）を指定してください。

ソースから：

git clone https://github.com/djwmarcx/better-mealie-mcp
cd better-mealie-mcp
uv sync                     # install deps
cp .env.example .env        # then edit .env with your Mealie URL + token

認証（.env または環境変数で設定）：

変数	意味
MEALIE_BASE_URL	Mealie のベース URL（デフォルトは http://localhost:9925）
MEALIE_API_TOKEN	長期間有効な API トークン（推奨）— Mealie → Profile → Manage API Tokens
MEALIE_USERNAME / MEALIE_PASSWORD	代替手段：起動時にログインしてトークンを取得します
MEALIE_TIMEOUT	リクエストごとのタイムアウト（秒、デフォルトは 60）
MEALIE_VERIFY_SSL	TLS 証明書を検証します。自己署名証明書を受け入れる場合は false（デフォルトは true）
MCP_SERVER_NAME	クライアントに通知する MCP 名（デフォルトは Mealie）
MEALIE_INCLUDE_TAGS	これらの API グループのみを公開します。カンマ区切りです（例：recipes,organizers,foods）。ツールを減らすことでコンテキストを軽量化し、ツール数に上限があるクライアントにも対応できます
MEALIE_EXCLUDE_TAGS	これらのグループ以外をすべて公開します（例：admin,households）
MEALIE_SLIM_SCHEMAS	冗長なスキーマ情報を削減します — デフォルトは true（以下のモードを参照）
MEALIE_SLIM_AGGRESSIVE	nullable な anyOf ユニオンもまとめます — デフォルトは false
MEALIE_VALIDATE_OUTPUT	ツールごとの出力スキーマを出力し、結果を検証します — デフォルトは false

グループは API のパスの最初のセグメントです（recipes、households、admin、 organizers、users、explore、foods、units など）。未設定の場合、すべてのツールが対象です。 両方が設定されている場合は INCLUDE が優先されます。現在のグループと各グループの内容は TOOLS.md を参照するか、 セットアップウィザードに選択させてください。ウィザードの グループ選択機能（Cooking や Meal planning など、ワンクリックで選べるパック付き）を使うと、 MEALIE_INCLUDE_TAGS が自動入力されます。

コンテキストサイズ（スキーマの詳細度）

このサーバーが公開するすべてのツールは、リクエストのたびに JSON スキーマをモデルに送信します。 この「アイドルコンテキスト」は、ツールが実際に呼び出されるまで純粋なオーバーヘッドです。 全 259 個のツールでは完全なスキーマが約 240k トークンになるため、サーバーはこれを削減します。 3 つのプリセットモードがあり、すべてのエンドポイントを引き続き呼び出せます。変わるのはモデルに表示される スキーマの詳細度のみです。

モード	環境変数	アイドルコンテキスト	動作
Lean（デフォルト）	（なし — デフォルト）	約 61k トークン	冗長な title（FastAPI がフィールド名から自動生成するもの）と、重複する default を削除し、出力／レスポンススキーマを省略します。呼び出し可能な機能は失われません。
Leanest	MEALIE_SLIM_AGGRESSIVE=true	約 51k トークン	Lean のすべての処理に加えて、nullable な anyOf:[{X},{null}] ユニオンを X にまとめます（「null を許可」という明示的なヒントを削除します）。
Full	MEALIE_SLIM_SCHEMAS=false MEALIE_VALIDATE_OUTPUT=true	約 240k トークン	入力と出力の完全な未削減スキーマを使用し、クライアント側で結果を検証します。構造化出力スキーマに依存するクライアントを使う場合にのみ選択してください。

モデルが正しい呼び出しを行うために必要な情報（format、実際の description、必須フィールド）は、どのモードでも保持されます。上記のタグフィルタリングと組み合わせると、 さらに削減できます。セットアップウィザードでは、 選択した組み合わせに応じたトークン数の推定値をリアルタイムで確認できます。

▶️ 実行

uv run better-mealie-mcp             # stdio transport (for MCP clients)
uv run better-mealie-mcp --http 8000 # streamable-http on 127.0.0.1:8000
uv run server.py                     # same server, back-compat entry
fastmcp run fastmcp.json             # via FastMCP project config (stdio)
fastmcp run fastmcp-http.json        # via FastMCP project config (http)

--http モードでは、バインドアドレスは MCP_HOST で指定します（デフォルトは 127.0.0.1。 Docker イメージでは、-p によるポートマッピングが機能するよう 0.0.0.0 が設定されています）。

🧪 ローカルの Mealie に対するテスト（Docker）

docker run -d --name mealie -p 9925:9000 \
  -e ALLOW_SIGNUP=true -e BASE_URL=http://localhost:9925 -e TZ=UTC \
  ghcr.io/mealie-recipes/mealie:latest

デフォルトの管理者ログイン情報：[email protected] / MyPassword。

📝 注意事項

• すべてのエンドポイントを公開すると、ツールが大量になり、アイドルコンテキストも大きくなります。 ほとんどの クライアントでは問題なく処理できます。クライアントのツール数に上限がある場合や、コンテキストを軽量化したい場合は、 MEALIE_INCLUDE_TAGS / MEALIE_EXCLUDE_TAGS（セットアップを参照）またはウィザードのグループ選択機能で ツールセットを絞り込んでください。

バージョン管理

この MCP のバージョンは、仕様の対象となる Mealie のバージョンと同じです — MCP 3.20.1 ⇒ Mealie v3.20.1。サーバーはこのバージョンをクライアントに通知し、 VERSIONS.md には各リリースと Mealie のバージョンおよび日付の対応が記載されています。

Mealie のバージョンに変更がない MCP のみの変更（機能や修正）は、同じ Mealie バージョンのリビジョンとしてリリースされます。つまり、REVISION カウンターが増え、リリース／イメージタグに -r<n> のサフィックスが付きます。例：v3.20.1-r2（-r1 はベース版で、サフィックスは付きません）。Mealie のバージョンが新しくなると、カウンターはリセットされます。:latest は常に最新のビルドを指します。

openapi.json は Mealie の仕様のベンダーコピーです。update-spec ワークフローは毎日実行され、最新の安定版 Mealie リリース（mealie:latest）を自動追跡します。このワークフローはそのイメージを起動し、/api/app/about から実際のバージョン（MEALIE_VERSION）を読み取り、/openapi.json を取得して、TOOLS.md とカウントを再生成します。そして、仕様に実際の変更があった場合に限り、バージョンを更新してプルリクエストを作成します（main は保護されているため、すべての変更は PR 経由で取り込まれます）。その PR がマージされると、release-on-spec がリリースを作成します（仕様を添付し、追加／削除されたツールをリリースノートに記載します）。変動するサーバークロックのデフォルト値は除外されるため、変更がない場合は何も行われません。

最新バージョンの追跡をやめて特定のリリースに固定するには、ワークフローの MEALIE_TAG_DEFAULT に特定のタグ（例：v3.20.1）を設定するか、mealie_tag 入力（latest、nightly、または任意のタグ）を指定して手動で実行してください。

• 一部のエンドポイント（list_auth_oauth*）は、Mealie 側で OIDC が設定されていないと 500 を返します。これは Mealie の動作であり、サーバーの問題ではありません。

📄 ライセンス

MIT ライセンス