mealie-mcp-server

mealie-mcp-server === [](https://github.com/timo-reymann/mealie-mcp-server/blob/main/LICENSE) [](https://github.com/timo-reymann/mealie-mcp-server/actions/workflows/ci.yml) [](https://github.com/timo-reymann/mealie-mcp-server/releases) [](https://renovatebot.com) A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Mealie](https://github.com/mealie-recipes/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. <p align="center"> <img src="https://raw.githubusercontent.com/timo-reymann/mealie-mcp-server/main/.github/images/logo.png" alt="Logo" /> <br /> Interact with your Mealie recipe database through AI assistants via the MCP protocol. </p> ## 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](https://nodejs.org/) >= 22 - A running [Mealie](https://github.com/mealie-recipes/mealie) instance with an API key ## Installation ### Quick start (npx) ```bash 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`: ```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" } } } } ``` ### Local development ```bash 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](./API_COVERAGE.md) for a detailed breakdown of all 42 tools and their corresponding Mealie API endpoints. ## Contributing I love your input! Please read the [Contribution Guidelines](./CONTRIBUTING.md) to get started. ## Development ### Requirements - [Node.js](https://nodejs.org/) >= 22 - [Yarn](https://yarnpkg.com/) (via Corepack: `corepack enable`) - A [Mealie](https://github.com/mealie-recipes/mealie) instance for integration testing (or mock the fetch layer) ### Test ```bash yarn test ``` ### Typecheck ```bash yarn typecheck ``` ### Build ```bash yarn build ``` ### Lint ```bash 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](./LICENSE)