Skip to content
Back to search

mealie-mcp-server

MCP server that exposes Mealie APIs to MCP clients such as Claude Desktop

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rldiao--mealie-mcp-server/badge.svg)](/listings/rldiao--mealie-mcp-server)

HTML

<a href="/listings/rldiao--mealie-mcp-server"><img src="/api/listings/rldiao--mealie-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.12+ - A running Mealie instance and an API key from your account settings - Package manager [uv](https://docs.astral.sh/uv/getting-started/installation/)

Installation

Option 1: Using the MCP SDK CLI (Recommended)

Clone the repository, then install the server into Claude Desktop with the `mcp` command supplied by the Python MCP SDK (no standalone `fastmcp` package is needed):

git clone https://github.com/rldiao/mealie-mcp-server.git
cd mealie-mcp-server
uv sync --locked
uv run mcp install src/server.py --with-editable . \
  --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  --env-var MEALIE_API_KEY=your-mealie-api-key

Option 2: Using uvx

Add this to your MCP client's configuration to run directly from GitHub without cloning (in Claude Desktop, use `claude_desktop_config.json`):

{
  "mcpServers": {
    "mealie-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rldiao/mealie-mcp-server",
        "mealie-mcp-server"
      ],
      "env": {
        "MEALIE_BASE_URL": "https://your-mealie-instance.com",
        "MEALIE_API_KEY": "your-mealie-api-key"
      }
    }
  }
}

Restart Claude Desktop to load the server.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 531 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Mealie MCP Server
  2. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/rldiao-mealie-mcp-server-badge.png)](https://mseep.ai/app/rldiao-mealie-mcp-server)
  3. A Model Context Protocol (MCP) server that connects AI assistants to your
  4. [Mealie](https://github.com/mealie-recipes/mealie) recipe database through clients
  5. such as Claude Desktop.
  6. ## Contents
  7. - [Features](#features)
  8. - [Quick Start](#quick-start)
  9. - [Configuration](#configuration)
  10. - [Remote Access](#remote-access)
  11. - [Docker](#docker)
  12. - [Usage Examples](#usage-examples)
  13. - [Available Tools](#available-tools)
  14. - [Development](#development)
  15. - [Important Notes](#important-notes)
  16. - [Support and Contributing](#support-and-contributing)
  17. - [License and Credits](#license-and-credits)
  18. ## Features
  19. - **Recipes:** Create, read, update, import, duplicate, and delete recipes.
  20. - **Search:** Filter by text, categories, tags, and tools with AND/OR logic.
  21. - **Images and assets:** Upload recipe images and files, or set images from URLs.
  22. - **Nutrition and display:** Set per-serving nutrition and recipe visibility
  23. settings such as `showAssets` and `showNutrition`.
  24. - **Ingredients:** Resolve free-text ingredients against Mealie's food and unit
  25. vocabulary.
  26. - **Shopping lists:** Manage lists and items, perform bulk operations, and add
  27. recipe ingredients with quantity scaling.
  28. - **Organization:** Manage categories, tags, foods, units, and recipe tools; find
  29. unused categories and tags.
  30. - **Meal planning:** View, create, update, and delete meal plan entries, create
  31. multiple entries, and mark recipes as made today.
  32. ## Quick Start
  33. ### Prerequisites
  34. - Python 3.12+
  35. - A running Mealie instance and an API key from your account settings
  36. - Package manager [uv](https://docs.astral.sh/uv/getting-started/installation/)
  37. ### Installation
  38. #### Option 1: Using the MCP SDK CLI (Recommended)
  39. Clone the repository, then install the server into Claude Desktop with the
  40. `mcp` command supplied by the Python MCP SDK (no standalone `fastmcp` package
  41. is needed):
  42. ```bash
  43. git clone https://github.com/rldiao/mealie-mcp-server.git
  44. cd mealie-mcp-server
  45. uv sync --locked
  46. uv run mcp install src/server.py --with-editable . \
  47. --env-var MEALIE_BASE_URL=https://your-mealie-instance.com \
  48. --env-var MEALIE_API_KEY=your-mealie-api-key
  49. ```
  50. #### Option 2: Using uvx
  51. Add this to your MCP client's configuration to run directly from GitHub without
  52. cloning (in Claude Desktop, use `claude_desktop_config.json`):
  53. ```json
  54. {
  55. "mcpServers": {
  56. "mealie-mcp-server": {
  57. "command": "uvx",
  58. "args": [
  59. "--from",
  60. "git+https://github.com/rldiao/mealie-mcp-server",
  61. "mealie-mcp-server"
  62. ],
  63. "env": {
  64. "MEALIE_BASE_URL": "https://your-mealie-instance.com",
  65. "MEALIE_API_KEY": "your-mealie-api-key"
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. Restart Claude Desktop to load the server.
  72. ## Configuration
  73. Set environment variables in your MCP client configuration or shell. For a local
  74. checkout, you can also copy [`.env.template`](.env.template) to `.env` and fill in
  75. your instance details. Never commit your API key.
  76. | Variable | Default | Description |
  77. | --- | --- | --- |
  78. | `MEALIE_BASE_URL` | Required | Mealie base URL, including protocol and port if needed |
  79. | `MEALIE_API_KEY` | Required | API key from your Mealie account settings |
  80. | `MEALIE_ENABLE_AI_IMPORT` | `false` | Opt in to AI recipe import; accepts `true`/`false` (case-insensitive) |
  81. | `MCP_TRANSPORT` | `stdio` | `stdio`, `streamable-http`, or legacy `sse` |
  82. | `MCP_HOST` | `127.0.0.1` | HTTP bind address; use `0.0.0.0` in containers |
  83. | `MCP_PORT` | `8765` | HTTP port, from 1 to 65535 |
  84. | `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL` |
  85. ## Remote Access
  86. The default stdio transport is for local clients. To serve HTTP clients, configure
  87. your Mealie credentials as described above and run from the checkout:
  88. ```bash
  89. export MCP_TRANSPORT=streamable-http
  90. export MCP_HOST=127.0.0.1
  91. export MCP_PORT=8765
  92. uv run mealie-mcp-server
  93. ```
  94. The server will expose its MCP endpoint at `http://<host>:<port>/mcp`.
  95. **Security:** HTTP transports have no built-in authentication. Anyone who can
  96. reach the endpoint can use the configured Mealie credentials through its tools.
  97. Keep it on a trusted interface; for remote access, use a reverse proxy that
  98. enforces authentication and HTTPS.
  99. ## Docker
  100. The [Dockerfile](Dockerfile) runs the server as a persistent container.
  101. ### Build
  102. ```bash
  103. docker build -t mealie-mcp-server .
  104. ```
  105. ### Standalone
  106. ```bash
  107. docker run -d \
  108. --name mealie-mcp \
  109. -e MEALIE_BASE_URL=http://your-mealie-host:9000 \
  110. -e MEALIE_API_KEY=your-mealie-api-key \
  111. -e MCP_TRANSPORT=streamable-http \
  112. -e MCP_HOST=0.0.0.0 \
  113. -e MCP_PORT=8765 \
  114. -p 127.0.0.1:8765:8765 \
  115. mealie-mcp-server
  116. ```
  117. The port is published only on the host's loopback interface. See
  118. [Remote Access](#remote-access) before making it reachable remotely.
  119. ### Docker Compose
  120. Add this service to the Compose file that runs Mealie. The example assumes that
  121. the Mealie service is named `mealie` and both services use a network named
  122. `mealie_net`, defined in that Compose file. Set `MEALIE_API_KEY` in the shell or
  123. Compose `.env` file.
  124. ```yaml
  125. services:
  126. mealie-mcp:
  127. build: .
  128. container_name: mealie-mcp
  129. restart: unless-stopped
  130. environment:
  131. MEALIE_BASE_URL: http://mealie:9000
  132. MEALIE_API_KEY: ${MEALIE_API_KEY}
  133. MCP_TRANSPORT: streamable-http
  134. MCP_HOST: "0.0.0.0"
  135. MCP_PORT: "8765"
  136. expose:
  137. - "8765"
  138. networks:
  139. - mealie_net
  140. ```
  141. `expose` does not publish a host port. Connect a reverse proxy on the same network
  142. for remote access, following the [HTTP security guidance](#remote-access).
  143. ## Usage Examples
  144. ```text
  145. "Search for chicken recipes"
  146. "Create a new recipe for pasta carbonara"
  147. "Mark the meatloaf recipe as made today"
  148. "Create a shopping list for this week"
  149. "Add all ingredients from the lasagna recipe to my shopping list"
  150. "Plan chicken soup for lunch on Friday"
  151. ```
  152. See [Usage Examples](USAGE_EXAMPLES.md) for detailed workflows and troubleshooting.
  153. ## Available Tools
  154. ### Recipe Tools (12 operations)
  155. - `get_recipes` - List/search recipes with advanced filtering
  156. - `get_recipe` - Get complete recipe details, or a summary with `concise=true`
  157. - `create_recipe` - Create a recipe; only the name is required, with optional
  158. ingredients, instructions, metadata, nutrition, and display settings
  159. - `import_recipe_from_url` - Import a recipe from a web page
  160. - `update_recipe` - Update content or metadata, including nutrition and display
  161. settings; omitted fields are preserved, and empty lists clear content
  162. - `duplicate_recipe` - Clone a recipe
  163. - `mark_recipe_last_made` - Update last made timestamp
  164. - `set_recipe_image_from_url` - Set image from URL
  165. - `upload_recipe_image_file` - Upload image file
  166. - `upload_recipe_asset_file` - Upload document/asset
  167. - `update_recipe_categories_and_tags` - Replace or clear categories, tags, or both using IDs
  168. - `delete_recipe` - Delete recipe
  169. ### Shopping List Tools (15 operations)
  170. - `get_shopping_lists` - List all shopping lists
  171. - `create_shopping_list` - Create new list
  172. - `get_shopping_list` - Get list by ID
  173. - `update_shopping_list` - Rename a list while preserving other fields
  174. - `delete_shopping_list` - Delete list
  175. - `add_recipe_to_shopping_list` - Add recipe ingredients
  176. - `remove_recipe_from_shopping_list` - Remove recipe ingredients
  177. - `get_shopping_list_items` - List all items
  178. - `get_shopping_list_item` - Get item by ID
  179. - `create_shopping_list_item` - Create single item
  180. - `create_shopping_list_items_bulk` - Create multiple items
  181. - `update_shopping_list_item` - Update item (preserves fields)
  182. - `update_shopping_list_items_bulk` - Update multiple items
  183. - `delete_shopping_list_item` - Delete single item
  184. - `delete_shopping_list_items_bulk` - Delete multiple items
  185. ### Category Tools (6 operations)
  186. - `get_categories` - List/search categories
  187. - `get_empty_categories` - Find unused categories
  188. - `create_category` - Create new category
  189. - `get_category` - Get by exactly one of `category_id` or `category_slug`
  190. - `update_category` - Update category
  191. - `delete_category` - Delete category
  192. ### Tag Tools (6 operations)
  193. - `get_tags` - List/search tags
  194. - `get_empty_tags` - Find unused tags
  195. - `create_tag` - Create new tag
  196. - `get_tag` - Get by exactly one of `tag_id` or `tag_slug`
  197. - `update_tag` - Update tag
  198. - `delete_tag` - Delete tag
  199. ### Food Tools (5 operations)
  200. - `get_foods` - List/search foods (resolve IDs for structured ingredients)
  201. - `create_food` - Create a new food
  202. - `get_food` - Get by ID
  203. - `update_food` - Update food
  204. - `delete_food` - Delete food
  205. ### Unit Tools (5 operations)
  206. - `get_units` - List/search units
  207. - `create_unit` - Create a new unit
  208. - `get_unit` - Get by ID
  209. - `update_unit` - Update unit
  210. - `delete_unit` - Delete unit
  211. ### Kitchen Tools (5 operations)
  212. - `get_tools` - List/search recipe tools (includes `householdsWithTool`)
  213. - `create_tool` - Create a new tool
  214. - `get_tool` - Get by exactly one of `tool_id` or `tool_slug`
  215. - `update_tool` - Update tool
  216. - `delete_tool` - Delete tool
  217. ### Parser Tools (1 operation)
  218. - `parse_ingredients` - Resolve one or more ingredient lines in one request; always returns a list
  219. ### Meal Plan Tools (6 operations)
  220. - `get_all_mealplans` - List meal plans
  221. - `create_mealplan` - Create meal plan entry
  222. - `create_mealplan_bulk` - Create multiple entries
  223. - `update_mealplan` - Update an entry while preserving omitted fields
  224. - `delete_mealplan` - Delete an entry
  225. - `get_todays_mealplan` - Get today's meals
  226. **Total: 61 tools**
  227. With `MEALIE_ENABLE_AI_IMPORT=true`, `import_recipe_with_ai` adds one optional
  228. recipe operation: **62 total tools, including 13 recipe tools**. It is absent
  229. from discovery and cannot be called when disabled.
  230. ### Migrating consolidated tools (breaking change)
  231. Redundant MCP names have been removed, not retained as aliases. Refresh your
  232. client's tool list and update saved calls:
  233. | Removed tool | Replacement |
  234. | --- | --- |
  235. | `create_recipe_full` | `create_recipe` with the same arguments |
  236. | `get_recipe_detailed` | `get_recipe` (full details by default) |
  237. | `get_recipe_concise` | `get_recipe` with `concise=true` |
  238. | `patch_recipe` | `update_recipe` with the same arguments |
  239. | `set_recipe_categories` | `update_recipe_categories_and_tags` with `category_ids` |
  240. | `set_recipe_tags` | `update_recipe_categories_and_tags` with `tag_ids` |
  241. | `get_category_by_slug` | `get_category` with `category_slug` |
  242. | `get_tag_by_slug` | `get_tag` with `tag_slug` |
  243. | `get_tool_by_slug` | `get_tool` with `tool_slug` |
  244. | `parse_ingredient` | `parse_ingredients(ingredients=[...])`; read the first result |
  245. Existing `create_recipe` and `update_recipe` calls remain supported. Recipe
  246. updates can now combine content and metadata, with omitted or null fields left
  247. unchanged. Ingredient and instruction lists replace only the provided fields.
  248. Nutrition remains a whole-object replacement, while settings are merged.
  249. Distinct operations remain separate: single and bulk writes have different
  250. response/failure contracts; paginated lists differ from individual lookups,
  251. unused-organizer queries, and today's meal plans. Recipe URL import, image URL
  252. scraping, and file uploads also perform different operations.
  253. ### Optional AI recipe import
  254. Set `MEALIE_ENABLE_AI_IMPORT=true` in your MCP client's environment, shell, or
  255. local `.env`. Restart the server and refresh the client's tool list. This applies
  256. to stdio, SSE, and Streamable HTTP. Offline SDK discovery remains configuration-
  257. and network-free, listing only default tools; optional registration occurs at
  258. runtime startup (or when passing an explicit enabled `ServerConfig`).
  259. `import_recipe_with_ai` requires **Mealie 3.23.0+** and a default AI provider
  260. configured for the API user's group. It accepts any combination of:
  261. - `content`: plain text, raw HTML, or JSON; also used for corrections or notes.
  262. - `url`: an HTTP(S) recipe or video URL, fetched by Mealie and saved as the source.
  263. - `image_paths`: ordered image paths accessible to the **MCP server's filesystem**,
  264. not a remote caller's computer. Multiple photos become one recipe; the first
  265. becomes its cover image.
  266. At least one nonblank source is required. Sources are combined, with pasted
  267. content taking precedence when they disagree. Optional `translate_language`
  268. requests translation. `create_new_organizers` defaults to `false`: matching
  269. existing tags, categories, and kitchen tools may be assigned, but new ones are
  270. created only when explicitly requested.
  271. Before each import the server reads `/api/groups/self` to check `aiEnabled` and,
  272. for photos, `imageProviderEnabled`. Missing/malformed capabilities or a failed
  273. lookup produce an explicit error, not a silent disabled result. Video detection
  274. and the audio-provider requirement are handled by Mealie. These checks establish
  275. configuration, not provider connectivity, credentials, or available quota.
  276. **This tool immediately creates and saves a recipe.** Source material is processed
  277. by Mealie's configured AI providers and may incur charges. Review the returned
  278. recipe for accuracy. The import has a 300-second read timeout; other API calls
  279. retain their existing timeouts. No imports are automatically retried. After a
  280. timeout or connection failure, check Mealie before retrying or switching tools:
  281. creation may already have succeeded. If the follow-up fetch fails, the error
  282. includes `created_slug` and `stage`; retrieve that recipe rather than importing again.
  283. Choose the tool according to the task:
  284. | Task | Tool |
  285. | --- | --- |
  286. | Ordinary recipe webpage | `import_recipe_from_url` |
  287. | Unstructured text, photos, video, combined sources, translation, or explicit AI import | `import_recipe_with_ai` (opt-in) |
  288. | Save already-composed ingredients and instructions | `create_recipe` |
  289. | Attach a photo to an existing recipe without extracting content | `upload_recipe_image_file` |
  290. The opt-in controls only this new tool. It does not disable Mealie's own AI
  291. fallback for URL scraping or other existing AI features. See
  292. [Mealie's AI import documentation](https://mealie.io/documentation/getting-started/installation/ai-providers/#import-with-ai)
  293. and [usage examples](USAGE_EXAMPLES.md#optional-ai-import).
  294. ## Development
  295. ### Setup
  296. After [cloning the repository](#installation), install development dependencies:
  297. ```bash
  298. uv sync --locked --extra dev
  299. ```
  300. For manual testing, configure your Mealie instance:
  301. ```bash
  302. cp .env.template .env
  303. # Edit .env with your Mealie instance details
  304. ```
  305. Launch the MCP Inspector:
  306. ```bash
  307. uv run mcp dev src/server.py
  308. ```
  309. Run the offline checks; these do not require a Mealie instance or credentials:
  310. ```bash
  311. uv run ruff check src tests
  312. uv run pytest -q
  313. ```
  314. ### Project Structure
  315. | Path | Purpose |
  316. | --- | --- |
  317. | [`src/mealie/`](src/mealie/) | HTTP client and API mixins |
  318. | [`src/tools/`](src/tools/) | FastMCP tool definitions and registration |
  319. | [`src/models/`](src/models/) | Pydantic request and response models |
  320. | [`src/server.py`](src/server.py) | Configuration, lifecycle, and entry point |
  321. | [`src/prompts.py`](src/prompts.py) | MCP prompts |
  322. | [`tests/`](tests/) | Offline tests and fixtures |
  323. Repository conventions are in [AGENTS.md](AGENTS.md), with focused guidance for
  324. [source code](src/AGENTS.md) and [tests](tests/AGENTS.md).
  325. The automated suite uses fake HTTP responses and includes local HTTP-transport
  326. checks. It does not replace compatibility testing against your deployed Mealie
  327. version.
  328. ## Important Notes
  329. The calls below use Python-style notation to illustrate MCP tool arguments; they
  330. are not standalone Python scripts.
  331. ### Filtering by Tags and Categories
  332. When filtering recipes, you **must use slugs or UUIDs**, not display names:
  333. Use `get_tags()` or `get_categories()` first to find the correct slugs:
  334. ```python
  335. get_recipes(tags=["quick-meals", "healthy"])
  336. ```
  337. For example, pass `quick-meals`, not the display name `Quick Meals`.
  338. ### Nutrition Is Replaced, Not Merged
  339. Mealie replaces the whole `nutrition` object on write. `update_recipe` follows
  340. suit, so pass every value you want to keep:
  341. ```python
  342. # Clears every nutrition value except fat.
  343. update_recipe(slug="...", nutrition={"fatContent": "12"})
  344. ```
  345. ### Parsing Ingredients in Bulk
  346. Resolving ingredients by hand costs one to two `get_foods` / `get_units` calls
  347. each. `parse_ingredients` does a whole recipe in one request and returns results
  348. that can be handed straight to `create_recipe`:
  349. ```python
  350. parse_ingredients(ingredients=["1/4 cup chopped onion", "2 large eggs"])
  351. # -> [{"input": "1/4 cup chopped onion", "confidence": 0.99, "quantity": 0.25,
  352. # "unit": {"id": "...", "name": "cup"},
  353. # "food": {"id": "...", "name": "onion"}, "note": "chopped"}, ...]
  354. ```
  355. A `null` unit or food means your instance has no matching entry; create one
  356. with `create_food` / `create_unit`, or leave the text in the note. Pass
  357. `verbose=True` for Mealie's full response including per-field confidences.
  358. ### Uploaded Assets and Nutrition Can Be Stored but Hidden
  359. A recipe's `settings` object controls what the UI renders. `showAssets` and
  360. `showNutrition` gate the assets and nutrition cards, so an asset uploaded with
  361. `upload_recipe_asset_file` can be present in the API response and still be
  362. invisible in the web UI. Flip the toggle with:
  363. ```python
  364. update_recipe(slug="...", settings={"showAssets": True})
  365. ```
  366. Mealie seeds a new recipe's settings from the household preferences
  367. (`recipeShowAssets`, `recipeShowNutrition`, ...), so the defaults differ per
  368. instance. Check rather than assume.
  369. Only the toggles you pass are changed. The tool reads the recipe's current
  370. settings and sends the merged object, because Mealie does not reliably preserve
  371. toggles omitted from a settings PATCH.
  372. ### Field Preservation
  373. When updating shopping list items, both single and bulk updates fetch the current
  374. records and preserve omitted fields. You only need to specify the fields you
  375. want to change:
  376. ```python
  377. # Only updates 'checked' field, preserves note, quantity, etc.
  378. update_shopping_list_item(item_id="...", checked=True)
  379. ```
  380. Bulk shopping inputs accept snake_case names such as `shopping_list_id` and
  381. Mealie's camelCase names such as `shoppingListId`. Conflicting aliases and
  382. duplicate IDs in a bulk update are rejected before writing.
  383. ### Meal Plan Validation and Clearing
  384. Meal dates must use `YYYY-MM-DD`, and entry types must be `breakfast`, `lunch`,
  385. `dinner`, or `side`. Creation requires a recipe or a nonblank title. Bulk meal
  386. plans are validated in full before any entries are created.
  387. Omitted update fields remain unchanged. To remove an existing recipe link,
  388. use `update_mealplan(entry_id="...", clear_recipe=True, title="Leftovers")`.
  389. Do not combine `clear_recipe` with a replacement `recipe_id`.
  390. ### Recovering from Partially Completed Writes
  391. Recipe creation/population and bulk meal-plan creation require multiple API
  392. requests and are not atomic. If a later request fails, the tool error includes
  393. recovery information identifying completed work. Inspect that information and
  394. the current Mealie state rather than blindly retrying the entire operation.
  395. A failed or timed-out request may have completed remotely.
  396. ## Support and Contributing
  397. - Check the [changelog](CHANGELOG.md) for changes and migration notes.
  398. - Review the [usage guide](USAGE_EXAMPLES.md) and
  399. [Mealie documentation](https://docs.mealie.io).
  400. - Report problems through [GitHub issues](https://github.com/rldiao/mealie-mcp-server/issues).
  401. - For pull requests, follow the [development workflow](#development) and include
  402. tests for behavior changes.
  403. ## License and Credits
  404. Licensed under the [MIT License](LICENSE).
  405. - [Mealie](https://github.com/mealie-recipes/mealie) - The recipe management system
  406. - [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) - SDK and
  407. bundled FastMCP server
  408. - [Model Context Protocol](https://modelcontextprotocol.io) - Protocol documentation
  409. - [Claude Desktop](https://claude.ai/download)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.