mealie-mcp-server

A Model Context Protocol (MCP) server for Mealie recipe management. Exposes 43 tools and 1 prompt for AI assistants to search, create, and manage recipes, meal plans, shopping lists, categories, and tags.

Interact with your Mealie recipe database through AI assistants via the MCP protocol.

Features

• Recipe Management — Search, create, patch, duplicate, and delete recipes. Batch-fetch multiple recipes concurrently.
• Meal Planning — View, create, and bulk-create meal plans. Composite tool fetches meal plans with embedded recipe details (including nutrition) using concurrent batch requests, eliminating N+1 queries.
• Shopping Lists — Full CRUD for lists and items, bulk operations, and recipe-to-list integration.
• Categories & Tags — Full CRUD for organizing recipes, including empty-category/tag detection.
• Batch & Composite Tools — get_recipes_batch and get_recipes_detailed_batch for concurrent recipe lookup, get_mealplan_with_recipes for meal plans with embedded recipe data and client-side date filtering.
• Zero Runtime Dependencies Beyond the SDK — Uses native fetch, no axios or httpx.

Requirements

• Node.js >= 22
• A running Mealie instance with an API key

Installation

Quick start (npx)

MEALIE_BASE_URL=https://your-mealie-instance.com \
MEALIE_API_KEY=your-api-key \
npx mealie-mcp-server

opencode config

Add to your opencode.json:

{
  "mcp": {
    "mealie-mcp-server": {
      "type": "local",
      "command": ["npx", "mealie-mcp-server"],
      "enabled": true,
      "environment": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-api-key"
      }
    }
  }
}

Docker

Run the MCP server in a container:

docker run -d \
  --name mealie-mcp-server \
  -e MEALIE_BASE_URL=https://your-mealie-instance.com \
  -e MEALIE_API_KEY=your-api-key \
  ghcr.io/timo-reymann/mealie-mcp-server:latest

Or with Docker Compose:

version: '3.8'
services:
  mealie-mcp-server:
    image: ghcr.io/timo-reymann/mealie-mcp-server:latest
    environment:
      MEALIE_BASE_URL: https://your-mealie-instance.com
      MEALIE_API_KEY: your-api-key
    restart: unless-stopped

Local development

git clone https://github.com/timo-reymann/mealie-mcp-server.git
cd mealie-mcp-server
corepack enable
yarn install
cp .env.template .env
# Edit .env with your MEALIE_BASE_URL and MEALIE_API_KEY
yarn dev

Make sure MEALIE_BASE_URL and MEALIE_API_KEY are set in your environment or opencode config.

Documentation

See API Coverage for a detailed breakdown of all 42 tools and their corresponding Mealie API endpoints.

Contributing

I love your input! Please read the Contribution Guidelines to get started.

Development

Requirements

• Node.js >= 22
• Yarn (via Corepack: corepack enable)
• A Mealie instance for integration testing (or mock the fetch layer)

Test

yarn test

Typecheck

yarn typecheck

Build

yarn build

Lint

yarn lint

Available Tools (43 total)

Recipes (11)

get_recipes, get_recipe_detailed, get_recipe_concise, get_recipes_batch, get_recipes_detailed_batch, create_recipe, patch_recipe, duplicate_recipe, mark_recipe_last_made, set_recipe_image_from_url, delete_recipe

Meal Plans (5)

get_all_mealplans, get_mealplan_with_recipes, create_mealplan, create_mealplan_bulk, get_todays_mealplan

Categories (7)

get_categories, get_empty_categories, create_category, get_category, get_category_by_slug, update_category, delete_category

Tags (7)

get_tags, get_empty_tags, create_tag, get_tag, get_tag_by_slug, update_tag, delete_tag

Shopping Lists (13)

get_shopping_lists, create_shopping_list, get_shopping_list, update_shopping_list, delete_shopping_list, add_recipe_to_shopping_list, remove_recipe_from_shopping_list, get_shopping_list_items, create_shopping_list_item, create_shopping_list_items_bulk, update_shopping_list_item, delete_shopping_list_item, delete_shopping_list_items_bulk

License

MIT