Mealie MCP Server

An MCP (Model Context Protocol) server that enables LLMs to interact with Mealie - a self-hosted recipe manager and meal planner.

Features

• Recipe Management: List, view, create, update, and delete recipes
• Recipe Import: Import recipes from URLs (supports most recipe websites)
• Ingredient Parsing: Automatic parsing of natural language ingredients (e.g., "2 cups flour")
• Image Uploads: Upload images to recipes via base64 encoding
• Meal Planning: Create and manage meal plans with date scheduling
• Shopping Lists: Full CRUD for shopping list items, plus add recipe ingredients to lists
• Organization: Manage categories and tags for recipe organization
• Food Management: List and create food items

Installation

# Clone the repository
git clone https://github.com/your-username/mealie-mcp.git
cd mealie-mcp

# Install dependencies
pnpm install

# Build
pnpm run build

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Required environment variables:

Variable	Description
MEALIE_URL	URL of your Mealie instance (e.g., http://localhost:9925)
MEALIE_API_KEY	API key from Mealie (Settings → API Tokens)
ENABLED_TOOLS	(Optional) Comma-separated list of tools to enable

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mealie": {
      "command": "node",
      "args": ["/path/to/mealie-mcp/dist/index.js"],
      "env": {
        "MEALIE_URL": "http://localhost:9925",
        "MEALIE_API_KEY": "your-api-key"
      }
    }
  }
}

Remote HTTP mode (e.g. on a NAS)

For running the server on a different machine (Synology NAS, home server, etc.), use the HTTP transport. The SDK's Streamable HTTP transport lets Claude Desktop connect over the network.

Set these env vars:

MCP_TRANSPORT=http
PORT=3000
ALLOWED_HOSTS=nas.local,192.168.1.50   # Host header allowlist (DNS rebind protection)
MEALIE_URL=http://mealie:9000           # service name if on same compose network
MEALIE_API_KEY=...

Claude Desktop config:

{
  "mcpServers": {
    "mealie": {
      "url": "http://nas.local:3000/mcp"
    }
  }
}

With Docker

The bundled Dockerfile defaults to HTTP transport on port 3000.

docker build -t mealie-mcp .

docker run -p 3000:3000 \
  -e MEALIE_URL=http://host.docker.internal:9925 \
  -e MEALIE_API_KEY=your-api-key \
  -e ALLOWED_HOSTS=localhost \
  mealie-mcp

Compose service (attach to existing Mealie stack)

  mealie-mcp:
    build: ./mealie-mcp
    container_name: mealie-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - MEALIE_URL=http://mealie:9000
      - MEALIE_API_KEY=${MEALIE_API_KEY}
      - ALLOWED_HOSTS=nas.local,192.168.1.50
    depends_on:
      - mealie

Available Tools (25 total)

Recipes (6 tools)

Tool	Description
list_recipes	List all recipes with pagination
get_recipe	Get full recipe details by slug
create_recipe	Create a new recipe with ingredients and instructions
update_recipe	Update an existing recipe
delete_recipe	Delete a recipe
upload_recipe_image	Upload an image to a recipe (base64)

Recipe Import (2 tools)

Tool	Description
test_scrape_url	Test if a URL can be scraped for recipe data
create_recipe_from_url	Import a recipe by scraping a URL

Meal Planning (4 tools)

Tool	Description
list_meal_plans	List meal plans with optional date range filter
get_todays_meal_plan	Get today's planned meals
create_meal_plan	Create a meal plan entry for a specific date
delete_meal_plan	Delete a meal plan entry

Shopping Lists (6 tools)

Tool	Description
list_shopping_lists	List all shopping lists
get_shopping_list	Get shopping list with items
add_shopping_list_item	Add an item to a shopping list
update_shopping_list_item	Update an item (quantity, note, or check/uncheck)
delete_shopping_list_item	Remove an item from a shopping list
add_recipe_to_shopping_list	Add all ingredients from a recipe to a list

Organization (4 tools)

Tool	Description
list_categories	List all recipe categories
create_category	Create a new category
list_tags	List all recipe tags
create_tag	Create a new tag

Foods (2 tools)

Tool	Description
list_foods	List all foods/ingredients
create_food	Create a new food item

Debugging (1 tool)

Tool	Description
get_current_user	Get current API user info including group and household context

Important: Group Context

Mealie scopes data by group and household. When you create an API token, it inherits the group context of your current session. If recipes or other items you create via the API aren't visible in your browser:

1. Use the get_current_user tool to see which group the API token is associated with
2. Ensure your browser session is viewing the same group (check the URL path)
3. If needed, switch groups in Mealie's UI, then generate a new API token

Development

# Run in development mode
pnpm run dev

# Lint
pnpm run lint

# Format
pnpm run format

# Build
pnpm run build

Local Mealie Instance

Start a local Mealie instance for testing:

docker-compose up -d

This starts Mealie at http://localhost:9925.

License

MIT