recipal-mcp-unofficial
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@recipal-mcp-unofficial Clone my 'Vanilla Cupcake' recipe into 3 variants, swapping sugar for honey in each"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
recipal-mcp-unofficial
An MCP server for the ReciPal nutrition-label API. It lets an AI assistant read and edit your recipes, ingredients, and subrecipes directly — including bulk operations that would take hours in the web UI.
Unofficial. Not affiliated with, endorsed by, or supported by ReciPal. Built by users of the product against its public API.
Interim project — this repository will be archived. ReciPal is building an official MCP server. When theirs ships, this one will be updated to point at it and then archived read-only. Don't build anything load-bearing on it. See SUNSET.md.
You need an active paid ReciPal subscription. API access is a paid feature; the key comes from your account settings under API access. Without one, this server cannot do anything.
What it's for
ReciPal's web UI is fine for editing one recipe. It is painful when you need to do the same thing to forty of them — fix a serving size across a whole catalog, rename ingredients that came in with (copy) suffixes, or build a family of product variants that differ by one ingredient. This server exposes the API so an assistant can do that work in a loop, with a dry run first.
The tool that earns its keep is bulk_clone_and_swap: take one fully-configured recipe as a template, clone it N times, and swap a single ingredient in each clone. Label settings, tags, and serving sizes carry forward, so the clones come out consistent.
Related MCP server: cookwith-mcp
Scope
One restriction, and it comes from ReciPal: no assistant plugin packages. No Claude, ChatGPT, or other plugin bundle, and no submission to a plugin store — ReciPal will be publishing those themselves alongside their official MCP server. Pull requests that add assistant plugin packaging will be declined for that reason and no other.
Everything else is open. This is published to npm and installable with npx, and it is
named recipal-mcp-unofficial at ReciPal's suggestion so it cannot be mistaken for their
official server.
Install
Requires Node.js 18 or newer.
For users (npx)
npx -y recipal-mcp-unofficialRegister it with your MCP client. For Claude Code:
claude mcp add --transport stdio recipal-mcp-unofficial \
--env RECIPAL_API_KEY=your_key_here \
-- npx -y recipal-mcp-unofficialFor Claude Desktop, add to claude_desktop_config.json:
{
"mcpServers": {
"recipal-mcp-unofficial": {
"command": "npx",
"args": ["-y", "recipal-mcp-unofficial"],
"env": { "RECIPAL_API_KEY": "your_key_here" }
}
}
}Restart the client, then ask it to list your recipes. You should see 17 tools available. Full walkthrough in docs/SETUP.md.
For development (clone and build)
Use this to run an unpublished change or to work on the source:
git clone https://github.com/RBV801/recipal-mcp-unofficial.git
cd recipal-mcp-unofficial
npm install
npm run buildThen register the built build/index.js with an absolute path. Full walkthrough in docs/SETUP.md.
⚠️ Read this before pointing it at a catalog you care about
The confirm: true and dry_run guards are supplied by the model, not by you. They stop a vaguely-worded prompt from causing damage. They do not stop a determined or confused agent — an assistant that decides to delete a recipe will pass confirm: true in the same call. ReciPal has no undo.
Because of that, the genuinely destructive tools are off by default. Turning them on is a deliberate act by the person running the server, not something a conversation can do:
Environment variable | Enables | Why it's gated |
|
| Permanent data loss, no undo |
|
| Can call any endpoint with any method |
Everything else — all reads, and the ordinary create/update tools — works out of the box. The bulk tools are always available but default to dry_run: true, and refuse to execute unless the caller passes both dry_run: false and confirm: true.
Recommended practice regardless: work against a throwaway recipe first. Several endpoints behave differently from what the docs suggest (see Known limitations).
Configuration
Variable | Default | Purpose |
| — | Required. From ReciPal account settings → API access |
| off | Expose the two delete tools |
| off | Expose |
| off | Log full request bodies to stderr. Bodies contain recipe data and your client probably logs stderr to disk, so leave off routinely |
|
| Retries on HTTP 429 |
|
| Override the endpoint. Must be https and a |
| off | Permit a non- |
See .env.example.
Tools
20 tools total, 17 exposed by default. Generated reference with every parameter: docs/TOOLS.md.
Group | Tools |
Read |
|
Recipe writes |
|
Ingredient-line writes |
|
Bulk |
|
Escape hatch |
|
† disabled by default.
Write tools take an open fields object rather than a fixed parameter list. ReciPal's published docs truncate before the full recipe attribute list, so hardcoding field names would have meant guessing; instead fields is passed straight through, Rails-style form-encoded (recipe[name]=...). Undocumented attributes work without a code change. Set as_json: true if an endpoint prefers JSON.
Read a real recipe before writing to one. get_recipe on an existing recipe shows the exact attribute names your account uses.
Known limitations
These are real, verified against the live API, and worth knowing before you build on this:
PUT /recipe_ingredients/{id}silently ignoresingredient_id. It returns HTTP 200 with the original ingredient still attached. Swapping one ingredient for another must be done as delete-then-create, which is whatbulk_clone_and_swapdoes internally.ReciPal double-wraps almost every response —
{recipe: {recipe_ingredients: [{recipe_ingredient: {…}}]}}. Reading fields off the outer envelope yieldsundefinedwith no error. If you extend this server, use the existingunwrap()/extractRecords()helpers.Parameter names for
scale_recipeandcreate_subrecipeare not published. They work via pass-throughfields, but run each once against a throwaway recipe and read the response before looping.The docs list
/recipes/{id}/scaleasPUT;POSTis what actually works. Don't "fix" this without testing.No pagination helper.
list_recipesandlist_ingredientscap at 20 per page; larger values are silently reduced to 20, so walk pages yourself.A wrong or unowned ID returns
401 Unauthorized, not404. Requesting an ingredient or recipe your account does not own answers{"error":"NotAuthorized"}— identical to an authentication failure. If you get a 401 on a call that worked a moment ago, suspect the ID before you suspect your API key.Not every recipe attribute you pass is applied, and unknown ones fail silently. A
PUTreturns 200 having quietly dropped fields it does not recognise. Alwaysget_recipean existing recipe and copy the attribute names from the response rather than guessing.tagscannot be set throughupdate_recipe. A tags string returns 200 and is silently dropped; an array ortag_listreturns500 ArgumentError. In the same request,package_yield_quantity,packagesandskuall apply correctly, so this is specific to tags rather than to the encoding. Tags do carry forward whenscale_recipeclones a tagged template, which is currently the only reliable way to get them onto a new recipe.
Rate limits
ReciPal documents roughly 175,000 requests/week, 1,000/minute (HTTP 429 beyond that), and a maximum of 5 concurrent label renders. This server honours 429 with Retry-After and exponential backoff, warns on stderr when fewer than 100 requests remain, and runs every bulk loop strictly sequentially with a configurable delay. Do not parallelise label renders.
Development
npm run typecheck # tsc --noEmit
npm run build # -> build/index.js
npm test # offline smoke tests, no API key or network needed
npm run gen:docs # regenerate docs/TOOLS.md from the running server
npm run verify # all of the abovedocs/TOOLS.md is generated by booting the built server and asking it for its own tool list, so the reference cannot drift from the code. CI fails if it's stale. If you add or change a tool, run npm run build && npm run gen:docs and commit the result.
Contributions welcome within the scope above — start with CONTRIBUTING.md, then docs/TESTING.md for how to verify changes against a live account, and docs/DESIGN.md for how the pieces fit.
License
"ReciPal" is a trademark of its owner and is used here only to describe what this software talks to.
Available Tools
17 toolsbulk_clone_and_swapA
The copy-and-swap loop. For each entry: clone template_recipe_id via scale_recipe, rename it, then replace the designated ingredient line with a different ingredient_id. Runs sequentially and independently per entry, so one failure does not poison the rest. Defaults to dry_run:true.
Inputs: entries (required), template_recipe_id (required), swap_recipe_ingredient_id (required), confirm, +2 more.
bulk_create_subrecipesA
Flag many recipes as subrecipes, sequentially. Defaults to dry_run:true — returns the plan without touching anything. Set dry_run:false AND confirm:true to execute. Returns a per-recipe success/failure report including the new ingredient_ids.
Inputs: recipe_ids (required), confirm, dry_run, delay_ms.
create_recipeA
Create a new empty recipe. POST /recipes. Prefer scale_recipe (clone a fully-configured template) when you need label settings to match existing recipes.
Inputs: fields (required), as_json.
create_recipe_ingredientA
Add an ingredient line to a recipe. POST /recipes/{id}/recipe_ingredients. Accepts ingredient_id (required) plus unit + quantity, or total_grams.
Inputs: fields (required), recipe_id (required), as_json.
create_recipe_shortcutA
Create a complete recipe with its ingredients in one request. POST /recipes/shortcut. The fastest path for building many recipes. Requires ingredient_ids and ingredient_weights: parallel lists of the same length, weights in grams. Either may be given as an array or a comma-separated string. Note this does NOT inherit label settings from an existing recipe -- serving size, package yield and tags all come back unset, so use scale_recipe to clone a configured template when label settings matter.
Inputs: fields (required), as_json.
create_subrecipeA
Flag an existing recipe as a subrecipe so it becomes usable as an ingredient in other recipes. POST /recipes/{id}/create_subrecipe. Returns the new ingredient record — capture its ingredient_id, that is what you add to other recipes.
Inputs: recipe_id (required), fields, as_json.
get_ingredientA
Get one ingredient with its full nutrition data and available units.
Inputs: ingredient_id (required).
get_recipeA
Get one recipe in full, including nutrition, serving size, package yield, tags and label settings. Use this to read a template recipe's exact settings before cloning it.
Inputs: recipe_id (required).
get_recipe_ingredientB
Get one ingredient line on a recipe.
Inputs: recipe_id (required), recipe_ingredient_id (required).
get_recipe_nutritionA
Get only the nutrition sub-object for a recipe.
Inputs: recipe_id (required).
list_ingredientsA
List the account's ingredient library. Subrecipes appear here once created, which is how you find the ingredient_id needed to add a subrecipe to another recipe. Paginated; per_page max 20. Larger values are silently reduced to 20, so callers must paginate.
Inputs: page, search, per_page.
list_recipe_ingredientsA
List every ingredient line on a recipe, with recipe_ingredient IDs, ingredient IDs, quantities, units and total_grams.
Inputs: recipe_id (required).
list_recipesA
List recipes from ReciPal with IDs, names, and tags. Paginated; per_page max 20. Larger values are silently reduced to 20, so callers must paginate.
Inputs: page, per_page.
scale_recipeA
Copy (and optionally scale) an existing recipe. POST /recipes/{id}/scale. This is the copy-and-swap primitive: cloning a configured template carries its label settings and tags forward, so you only replace one ingredient afterward. Pass a scale factor of 1 for a straight copy.
Inputs: recipe_id (required), fields, as_json.
update_ingredientA
Update an ingredient in the library. PUT /ingredients/{id}. Use for renaming (e.g. stripping '(copy)' suffixes).
Inputs: fields (required), ingredient_id (required), as_json.
update_recipeA
Update a recipe's attributes. PUT /recipes/{id}.
Inputs: fields (required), recipe_id (required), as_json.
update_recipe_ingredientA
Update one ingredient line. PUT /recipes/{id}/recipe_ingredients/{ri_id}. NOTE: this endpoint silently ignores ingredient_id — it returns 200 with the original ingredient still attached. To swap one ingredient for another you must delete the line and create a new one.
Inputs: fields (required), recipe_id (required), recipe_ingredient_id (required), as_json.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct resources or actions, and descriptions clearly separate list/get/create/update/bulk workflows. A few overlaps exist—get_recipe versus get_recipe_nutrition, and create_recipe versus create_recipe_shortcut versus scale_recipe—but the descriptions are detailed enough to prevent serious misselection.
Tool names consistently follow lowercase snake_case verb_noun patterns like list_recipes, get_recipe, create_recipe, update_recipe, and bulk_create_subrecipes. Compound names like create_recipe_shortcut and bulk_clone_and_swap are minor extensions but do not break the overall predictable convention.
17 tools is slightly above the ideal 3-15 range, but the count is justified by the combination of single-resource operations, bulk utilities, and shortcut creation. Each tool serves a recognizable recipe-management workflow, so the set feels somewhat heavy but not bloated.
The tool surface covers read, create, update, copy, and bulk operations, but there are no delete endpoints for recipes, ingredients, or recipe ingredient lines. This is a significant gap because update_recipe_ingredient silently ignores ingredient_id and the documentation explicitly says swapping requires deleting the line and creating a new one—yet no delete tool exists to complete that workflow.
Maintenance
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that transforms AI assistants into personal chefs by providing recipe recommendations and meal planning features based on the HowToCook repository.56,244 npm800ISC
- AlicenseBqualityDmaintenanceAn MCP server that enables AI-powered recipe generation and transformation using natural language, supporting dietary restrictions, allergies, and nutritional goals.213 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for MealMastery AI meal planning that enables users to manage meal plans, recipes, and grocery lists through natural language conversation with AI agents like Claude.57 npmMIT
- FlicenseAqualityDmaintenanceMCP server enabling AI assistants to manage recipes and ingredients in the WeekPlan app via its REST API.81-