mealie

Mealie MCP Server exposes a comprehensive set of MCP tools that let an AI assistant interact with a Mealie recipe database. The server leverages the uv-based Python runtime to connect to your local or remote Mealie instance via its API key, enabling recipe CRUD operations, advanced filtering, image and asset uploads, shopping list management, and meal planning capabilities. You can issue natural language prompts like searching for recipes, creating a new recipe, duplicating a recipe, or adding ingredients to a shopping list, and the MCP will translate them into corresponding tool calls (e.g., get_recipes, create_recipe, add_recipe_to_shopping_list). The server also provides guidance on how to structure queries using slugs or UUIDs for tags and categories and supports advanced filtering with AND/OR logic across entities. To use it, configure Claude Desktop (or another MCP client) to load the server, supply your Mealie base URL and API key, and then start issuing prompts that map to the 45 available tools across recipes, shopping lists, categories, tags, and meal plans.

Prerequisites:

• Python 3.12+
• A running Mealie instance with an API key
• The uv tool (uvX/uv) for Python package management

Option 1: Quick install with uv (recommended for local development)

1. Ensure you have uv installed and accessible in your environment.
2. Add the MCP server to Claude Desktop or your MCP client using the following directory setup (adjust paths as needed):

# Example: Run directly via uv, pointing to the server directory
uv sync
# Start the MCP server with the configuration provided in the README (adjust paths as needed)
uv run mcp dev src/server.py

Option 2: Manual configuration in Claude Desktop

1. Clone the repository and navigate to the project folder.
2. Install dependencies and prepare environment variables (Mealie base URL and API key).
3. Add the server configuration to your claude_desktop_config.json as shown:

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/repo/src",
        "run",
        "server.py"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

4. Restart Claude Desktop to load the server and begin issuing prompts.

Notes:

• The installation steps assume a local or accessible development environment where uv can execute the server entry point at src/server.py.
• If you prefer a containerized or different runtime, adapt the mcp_config accordingly (see additional notes below).

Tips and troubleshooting:

• Ensure MEALIE_BASE_URL is publicly accessible from where you run the MCP server if using Claude Desktop remotely.
• Keep your Mealie API key secure; do not hard-code it in shared config files.
• When filtering by tags or categories, always use slug values (e.g., quick-meals) or UUIDs as required by the API; display names will not work for filtering.
• If you modify the server or tooling, re-run uv sync or reload Claude Desktop to pick up changes.
• The MCP server supports 45 tools across four domains (recipes, shopping lists, categories, tags, meal plans); consult the README’s Tools section for the full list and exact function names.