mcp-wikibooks-cookbook
An MCP server for the Cookbook on
the English Wikibooks: thousands of recipes written and maintained in the open, with their
ingredients, their equipment and their steps. Search them, read one, and rescale it to the
number of people you are actually cooking for. No API key, no account, read-only.
(Version française plus bas / French version below)
Quickstart
One-click install
Claude Code
claude mcp add wikibooks-cookbook -- npx -y mcp-wikibooks-cookbook
Claude Desktop, Cursor, and any client using the standard config format
{
"mcpServers": {
"wikibooks-cookbook": {
"command": "npx",
"args": ["-y", "mcp-wikibooks-cookbook"]
}
}
}
Node 20 or later.
Bundle, without npm
Download mcp-wikibooks-cookbook-<version>.mcpb from
the latest release and
open it. A client that supports MCP bundles installs it on its own, with no npm and no
configuration file to edit.
| Tool | What it does | Key parameters |
|---|
search_recipes | Finds a page by dish name or by an ingredient it uses. | query, search, limit |
get_recipe | Reads one page, optionally rescaled. | id, servings, max_description_chars |
scale_ingredients | Rescales any English ingredient list, without the network. | ingredients, factor, from_servings |
list_recipes | Browses by cuisine, kind of dish or main ingredient. | cuisine, dish_type, main_ingredient, limit |
The server is read-only. It edits nothing on the wiki and uploads nothing.
The arithmetic is the point
Ask for a six-serving recipe scaled to four and a naive multiplication gives you 3.33 egg yolks
and 0.67 of a pinch of pepper. Neither is something a kitchen can produce, and a model that
repeats them is confidently wrong about a dish somebody is about to cook.
Six rules do the work.
A countable thing lands where a cook can divide it. Half an egg cannot be measured out, so a
count of eggs, yolks or whites lands on a whole number. Half a clove of garlic can be cut, so a
clove lands on a half. The rounded line says which way it moved.
A sealed packet is never cut. A can, a jar, a packet, a sheet of gelatine: opening one is
all or nothing, so those land on a whole one whatever the factor says.
A measurement moves to a smaller unit before it is rounded. A quantity that would fall below
one is demoted first, so 1 tablespoon quartered reads as 1 teaspoon rather than rounding away to
nothing. A large result climbs the other way, so 200 g scaled tenfold reads as 2 kg. Read
amount together with unit and never on its own: the bare number can shrink while the
quantity grows.
An approximate measure is multiplied as a count, never converted. A pinch, a dash, a glug, a
dollop, a capful, a spoonful: the size of one of them belongs to whoever pours it, and the count
is what carries the recipe's proportion. A pinch taken from six servings to twenty-five is four
pinches. The everyday equivalence goes in the note, never in the quantity. English says as much
in the word itself: the -ful suffix means "as much as one of these holds", so a container that
has never come up is understood the first time it appears, and the gestures whose names give
nothing away are named one by one in the vocabulary.
A line publishing two quantities has both of them scaled. 450 g (1 pound) spaghetti comes
back with the metric figure and the imperial figure in step, so they cannot contradict each
other, and so does one written after a slash, as in 500 g / 1.1 lb. A line offering a choice,
as in 2 tablespoons butter OR 30 g margarine, has both branches scaled, so whichever one the
cook takes carries the same share.
What cannot be multiplied is flagged rather than multiplied. "Salt to taste" comes back as
published, marked unscaled, and counted in the summary.
What a scaled ingredient looks like
Every line comes back in one shape:
{
"text": "300 g (11 ounces) flat noodles",
"original": "450 g (1 pound) flat noodles",
"scaling": "rounded",
"amount": 300,
"amount_max": null,
"unit": "g",
"note": "The amount is exact; the equivalent in brackets was rounded to stay readable."
}
scaling carries the honesty of the tool:
scaled — the arithmetic was exact.rounded — a countable thing was moved to a whole or a half, or a measurement was demoted to
a smaller unit to stay usable.unscaled — the line carries nothing that can be multiplied, so it was left as published and
flagged.
Reading a page
search_recipes
Find a page by dish name or by an ingredient it uses.
| Argument | Type | Default | Meaning |
|---|
query | string | — | A dish, such as carbonara, or an ingredient, such as guanciale |
search | text | title | text | text reads the whole page; title matches the page name only |
limit | integer 1–50 | 10 | Rows to return |
Returns { query, results, result_count, total_available, source, notes }. Each row carries
id, title, url, image_url, description and excerpt.
total_available is always null. The gateway publishes no total and offers no second page, so
any number here would be invented, and a short list is not evidence that little exists. Narrow
the query instead.
get_recipe
Read one page, optionally rescaled.
| Argument | Type | Default | Meaning |
|---|
id | string | — | Page key from a search, such as Cookbook:Spaghetti_alla_Carbonara |
servings | integer 1–500 | — | Rescale the ingredients to this many |
max_description_chars | integer | 1200 | Ceiling on the introduction |
Returns { id, title, url, yield, ingredients, equipment, steps, tips, prep_minutes, cook_minutes, total_minutes, time_text, category, categories, difficulty, difficulty_max, energy, author, rating, nutrition, description, attribution, license, revised_at, source, notes }.
yield is { original_count, original_text, requested, unit, factor }. original_text keeps
the page's own wording, because "4 to 6" and "4" are different claims. Rescaling needs a stated
yield: a page that publishes none comes back as published, and says so.
Ingredients are read from a bulleted list and from a table alike. Where a page lays them out as
a wikitable, the amount comes from whichever of the Count, Volume and Weight columns the row
fills, and a baker's percentage column is left out of it.
author and rating are always null: the Cookbook is written collectively and carries no
reader score. A time, a difficulty or a nutrition panel the page does not publish is null,
never zero and never inferred from the steps.
scale_ingredients
Rescale any English ingredient list. Makes no network request, so it works on a list pasted in
from anywhere.
| Argument | Type | Meaning |
|---|
ingredients | string[] | Ingredient lines |
factor | number | Multiplier. Use this, or the pair below |
from_servings + to_servings | number | The factor is computed from the two |
Returns { factor, ingredients, scaled_count, rounded_count, unscaled_count, notes }.
list_recipes
Browse by cuisine, kind of dish, or main ingredient. Give at least one of cuisine,
dish_type, main_ingredient; limit defaults to 15.
This is built on the Cookbook's search, because the route this server is allowed to use
publishes no way to list the members of a category. What comes back is a ranked sample rather
than the category itself: it is neither complete nor ordered, and its length says nothing about
how many recipes exist on the subject. The tool says so in its own notes.
What the answers claim
The Cookbook keeps recipes and reference pages in one namespace, so a search row can be a page
about an ingredient rather than a recipe using it. Only get_recipe can tell them apart, and it
says when a page carries no ingredient list rather than passing for a recipe with nothing in it.
A failure is never returned as an empty result. A request that could not be made comes back as
an error code, because silence about a failure becomes "there is no such recipe" in the mouth of
a model.
A rescale of a page that yielded no quantities reports no factor and says the page delivered
none, rather than announcing a multiplication over an empty list.
Licence and attribution
Cookbook pages are published under
Creative Commons Attribution-ShareAlike 4.0.
Repeating a recipe means two things: crediting Wikibooks and the page you took it from, and
sharing what you build on it under the same licence. get_recipe returns both license and the
page url so an answer can carry the credit with it.
This server's own code is MIT.
Configuration
Every setting is optional.
| Variable | Default | Meaning |
|---|
WB_USER_AGENT | — | Prefixed to this server's own identifier |
WB_MIN_INTERVAL_MS | 1000 | Milliseconds between requests. Refused below 500 or above 60000 |
WB_TIMEOUT_MS | 20000 | Per-request deadline. Accepted from 1000 to 120000 |
WB_MAX_RETRIES | 3 | Retries on a busy or rate-limited gateway. Up to 8 |
WB_CACHE_TTL_MS | 900000 | In-memory cache lifetime. 0 turns it off |
WB_CACHE_MAX_ENTRIES | 200 | Cache size |
WB_LOG_LEVEL | error | silent, error, info or debug. Goes to stderr |
A value that cannot be read warns on stderr and falls back, so one typo does not take away every
tool.
One request at a time, at least a second apart, widening when the gateway pushes back. The
User-Agent always ends with this project's name and address, whatever a caller sets, so
Wikimedia can reach a human about traffic it did not expect. The floor on the interval has a
hard minimum that configuration cannot go below.
Requests go to the Wikimedia developer gateway at api.wikimedia.org, which is the route
published for programs. The wiki's own /w/ paths are disallowed to robots on
en.wikibooks.org and are never called from here.
Using the client on its own
The layer that talks to the gateway imports nothing from the protocol and is published
separately, with the pacing, the cache and the error taxonomy attached.
import { CookbookClient } from "mcp-wikibooks-cookbook/client";
const client = new CookbookClient();
const { data } = await client.getRecipe("Cookbook:Spaghetti alla Carbonara");
console.log(data.ingredients, data.license?.url);
Troubleshooting
rate_limited — Wikimedia asked this client to slow down. It says nothing about whether the
recipe exists. Wait and ask again, or raise WB_MIN_INTERVAL_MS.
not_found — the gateway answered, and there is no page at that address. Search for the
name rather than guessing the key.
A search returns fewer rows than asked for — the Cookbook shares its wiki with every other
book on Wikibooks, and rows from elsewhere are dropped. The notes say how many.
A recipe comes back with no ingredients — the page may be about an ingredient or a technique
rather than a recipe. Lists and ingredient tables are both read, so an empty answer means the
page states its ingredients somewhere else. The notes say so; follow the url, and note that no
rescale is reported for a page that yielded no quantities.
parse_failure — the gateway answered in a shape this server cannot read. Please
open an issue with the arguments
you used.
Development
npm install
npm run typecheck
npm test
npm run build
npm run build:fixtures
WB_LIVE=1 npm run test:live
npm run inspector
Fixtures are generated rather than captured, so no wiki content lives in this repository, and
the unit suite never touches the network.
The access layer under src/wikibooks does not import the MCP SDK and is published separately
as mcp-wikibooks-cookbook/client, usable as a plain library. The arithmetic lives under
src/recipe.
Contributing
Bugs, questions and ideas all belong in
the issue tracker. Pull requests
are welcome; please open an issue first so we can agree on what the right answer is before you
write it. CONTRIBUTING.md has the detail, and SECURITY.md
covers anything exploitable.
Support
Free, and it stays free. If it saved you some time, you can
buy me a coffee.
License
MIT. See LICENSE. The licence covers this source code only, not the recipes retrieved
through it, which are published under Creative Commons Attribution-ShareAlike 4.0 and carry the
obligations that licence attaches.
This is an unofficial project, with no affiliation to or endorsement by Wikimedia or the
Wikibooks community.
mcp-wikibooks-cookbook (français)
Un serveur MCP pour le Cookbook des
Wikibooks anglophones : des milliers de recettes écrites et entretenues au grand jour, avec
leurs ingrédients, leur matériel et leurs étapes. Cherchez-les, lisez-en une, et remettez-la à
l'échelle du nombre de personnes que vous recevez vraiment. Sans clé d'API, sans compte, en
lecture seule.
Démarrage rapide
Installation en un clic
Claude Code
claude mcp add wikibooks-cookbook -- npx -y mcp-wikibooks-cookbook
Claude Desktop, Cursor, et tout client utilisant le format standard
{
"mcpServers": {
"wikibooks-cookbook": {
"command": "npx",
"args": ["-y", "mcp-wikibooks-cookbook"]
}
}
}
Node 20 ou plus récent.
Bundle, sans npm
Téléchargez mcp-wikibooks-cookbook-<version>.mcpb depuis
la dernière release et
ouvrez-le. Un client compatible l'installe seul, sans npm ni fichier de configuration à
modifier.
Outils
| Outil | Ce qu'il fait | Paramètres principaux |
|---|
search_recipes | Trouve une page par nom de plat ou par ingrédient qu'elle utilise. | query, search, limit |
get_recipe | Lit une page, avec remise à l'échelle facultative. | id, servings, max_description_chars |
scale_ingredients | Remet à l'échelle n'importe quelle liste anglaise, hors ligne. | ingredients, factor, from_servings |
list_recipes | Parcourt par cuisine, type de plat ou ingrédient principal. | cuisine, dish_type, main_ingredient, limit |
Le serveur est en lecture seule. Il ne modifie rien sur le wiki et n'envoie rien.
L'arithmétique est le cœur du sujet
Demandez une recette pour six ramenée à quatre : une multiplication naïve donne 3,33 jaunes
d'œuf et 0,67 pincée de poivre. Ni l'un ni l'autre ne se produit dans une cuisine, et un modèle
qui les répète se trompe avec aplomb sur un plat que quelqu'un s'apprête à cuisiner.
Six règles font le travail.
Un dénombrable atterrit là où un cuisinier peut le diviser. Un demi-œuf ne se mesure pas :
un nombre d'œufs, de jaunes ou de blancs tombe sur un entier. Une demi-gousse d'ail se coupe :
une gousse tombe sur une demie. La ligne arrondie dit dans quel sens elle a bougé.
Un emballage scellé n'est jamais coupé. Une boîte, un pot, un sachet, une feuille de
gélatine : on l'ouvre entièrement ou pas du tout, donc ceux-là tombent sur une unité entière
quel que soit le facteur.
Une mesure descend vers une unité plus petite avant d'être arrondie. Une quantité qui
passerait sous l'unité est d'abord convertie, si bien qu'une cuillère à soupe divisée par quatre
se lit une cuillère à café plutôt que de s'arrondir à rien. Un résultat élevé remonte dans
l'autre sens : 200 g multipliés par dix se lisent 2 kg. Lisez toujours amount avec unit : le
nombre nu peut diminuer pendant que la quantité augmente.
Une mesure approximative est multipliée comme un nombre, jamais convertie. Une pincée, un
trait, un bouchon, une cuillerée : la taille de l'une d'elles appartient à qui verse, et c'est
le nombre qui porte la proportion de la recette. Une pincée passée de six parts à vingt-cinq
fait quatre pincées. L'équivalence courante va dans la note, jamais dans la quantité. L'anglais
le dit dans le mot lui-même : le suffixe -ful signifie « autant qu'il en tient là-dedans », donc
un contenant jamais rencontré est compris dès sa première apparition, et les gestes dont le nom
ne dit rien de la taille sont nommés un par un dans le vocabulaire.
Une ligne portant deux quantités publiées voit ses deux branches mises à l'échelle.
450 g (1 pound) spaghetti revient avec la valeur métrique et la valeur impériale en accord,
sans se contredire, et il en va de même d'une valeur écrite après une barre oblique, comme
500 g / 1.1 lb. Une ligne offrant un choix, comme 2 tablespoons butter OR 30 g margarine,
voit ses deux branches mises à l'échelle, si bien que celle que prend le cuisinier porte la même
part.
Ce qui ne se multiplie pas est signalé plutôt que multiplié. « Salt to taste » revient tel
que publié, marqué unscaled, et compté dans le résumé.
À quoi ressemble un ingrédient mis à l'échelle
Chaque ligne revient dans la même forme :
{
"text": "300 g (11 ounces) flat noodles",
"original": "450 g (1 pound) flat noodles",
"scaling": "rounded",
"amount": 300,
"amount_max": null,
"unit": "g",
"note": "The amount is exact; the equivalent in brackets was rounded to stay readable."
}
scaling porte l'honnêteté de l'outil :
scaled — le calcul était exact.rounded — un dénombrable a été ramené à un entier ou à une demie, ou une mesure a été
descendue vers une unité plus petite pour rester utilisable.unscaled — la ligne ne porte rien de multipliable, elle est laissée telle que publiée et
signalée.
Lire une page
search_recipes
Trouve une page par nom de plat ou par ingrédient qu'elle utilise.
| Argument | Type | Défaut | Sens |
|---|
query | chaîne | — | Un plat, comme carbonara, ou un ingrédient, comme guanciale |
search | text | title | text | text lit toute la page ; title ne compare que le nom de la page |
limit | entier 1–50 | 10 | Nombre de lignes |
Renvoie { query, results, result_count, total_available, source, notes }. Chaque ligne porte
id, title, url, image_url, description et excerpt.
total_available vaut toujours null. La passerelle ne publie aucun total et n'offre pas de
seconde page : tout nombre ici serait inventé, et une liste courte ne prouve pas qu'il existe
peu de choses. Resserrez plutôt la requête.
get_recipe
Lit une page, avec remise à l'échelle facultative.
| Argument | Type | Défaut | Sens |
|---|
id | chaîne | — | Clé de page issue d'une recherche, comme Cookbook:Spaghetti_alla_Carbonara |
servings | entier 1–500 | — | Remet les ingrédients à ce nombre de parts |
max_description_chars | entier | 1200 | Plafond sur l'introduction |
Renvoie { id, title, url, yield, ingredients, equipment, steps, tips, prep_minutes, cook_minutes, total_minutes, time_text, category, categories, difficulty, difficulty_max, energy, author, rating, nutrition, description, attribution, license, revised_at, source, notes }.
yield vaut { original_count, original_text, requested, unit, factor }. original_text
conserve la formulation de la page, parce que « 4 to 6 » et « 4 » ne disent pas la même chose.
Une remise à l'échelle exige un rendement annoncé : une page qui n'en publie aucun revient telle
que publiée, et le dit.
Les ingrédients sont lus aussi bien en liste à puces qu'en tableau. Quand une page les présente
en wikitable, la quantité vient de celle des colonnes Count, Volume et Weight que la ligne
remplit, et une colonne de pourcentage boulanger est laissée de côté.
author et rating valent toujours null : le Cookbook s'écrit collectivement et ne porte
aucune note de lecteur. Un temps, une difficulté ou un tableau nutritionnel que la page ne
publie pas vaut null, jamais zéro, et n'est jamais déduit des étapes.
scale_ingredients
Remet à l'échelle n'importe quelle liste d'ingrédients en anglais. Ne fait aucune requête
réseau, donc fonctionne sur une liste collée depuis n'importe où.
| Argument | Type | Sens |
|---|
ingredients | chaîne[] | Lignes d'ingrédients |
factor | nombre | Multiplicateur. Utilisez-le, ou la paire ci-après |
from_servings + to_servings | nombre | Le facteur est calculé à partir des deux |
Renvoie { factor, ingredients, scaled_count, rounded_count, unscaled_count, notes }.
list_recipes
Parcourt par cuisine, type de plat ou ingrédient principal. Donnez au moins l'un de cuisine,
dish_type, main_ingredient ; limit vaut 15 par défaut.
C'est bâti sur la recherche du Cookbook, parce que la route que ce serveur a le droit d'utiliser
ne publie aucun moyen de lister les membres d'une catégorie. Ce qui revient est un échantillon
classé et non la catégorie elle-même : ce n'est ni complet ni ordonné, et sa longueur ne dit
rien du nombre de recettes existant sur le sujet. L'outil le dit dans ses propres notes.
Ce que les réponses affirment
Le Cookbook garde les recettes et les pages de référence dans un seul espace de noms : une ligne
de recherche peut donc être une page sur un ingrédient plutôt qu'une recette qui l'emploie. Seul
get_recipe sait les distinguer, et il dit quand une page ne porte pas de liste d'ingrédients
au lieu de la faire passer pour une recette vide.
Un échec n'est jamais renvoyé comme un résultat vide. Une requête qui n'a pas pu être faite
revient sous forme de code d'erreur, parce que le silence sur un échec devient « cette recette
n'existe pas » dans la bouche d'un modèle.
La remise à l'échelle d'une page qui n'a livré aucune quantité ne rapporte aucun facteur et dit
que la page n'en a donné aucune, plutôt que d'annoncer une multiplication sur une liste vide.
Licence et attribution
Les pages du Cookbook sont publiées sous
Creative Commons Attribution-Partage dans les mêmes conditions 4.0.
Reprendre une recette engage à deux choses : citer Wikibooks et la page dont elle vient, et
partager à l'identique ce que vous en tirez, sous la même licence. get_recipe renvoie à la
fois license et l'url de la page, pour qu'une réponse porte la mention avec elle.
Le code de ce serveur est sous MIT.
Configuration
Tous les réglages sont facultatifs.
| Variable | Défaut | Sens |
|---|
WB_USER_AGENT | — | Placé devant l'identifiant propre du serveur |
WB_MIN_INTERVAL_MS | 1000 | Millisecondes entre deux requêtes. Refusé sous 500 ou au-dessus de 60000 |
WB_TIMEOUT_MS | 20000 | Délai par requête. Accepté de 1000 à 120000 |
WB_MAX_RETRIES | 3 | Reprises sur passerelle occupée ou limitée. Jusqu'à 8 |
WB_CACHE_TTL_MS | 900000 | Durée de vie du cache mémoire. 0 le désactive |
WB_CACHE_MAX_ENTRIES | 200 | Taille du cache |
WB_LOG_LEVEL | error | silent, error, info ou debug. Sort sur stderr |
Une valeur illisible avertit sur stderr et retombe sur le défaut, pour qu'une faute de frappe
n'emporte pas tous les outils.
Une requête à la fois, au moins une seconde d'écart, en s'élargissant quand la passerelle
freine. Le User-Agent se termine toujours par le nom et l'adresse de ce projet, quoi qu'un
appelant y mette, pour que Wikimedia puisse joindre un humain à propos d'un trafic inattendu. Le
plancher sur l'intervalle a un minimum dur que la configuration ne peut pas franchir.
Les requêtes vont à la passerelle développeur de Wikimedia, api.wikimedia.org, la route
publiée pour les programmes. Les chemins /w/ du wiki lui-même sont interdits aux robots sur
en.wikibooks.org et ne sont jamais appelés d'ici.
Utiliser le client seul
La couche qui parle à la passerelle n'importe rien du protocole et est publiée séparément, avec
la cadence, le cache et la taxinomie d'erreurs.
import { CookbookClient } from "mcp-wikibooks-cookbook/client";
const client = new CookbookClient();
const { data } = await client.getRecipe("Cookbook:Spaghetti alla Carbonara");
console.log(data.ingredients, data.license?.url);
Dépannage
rate_limited — Wikimedia a demandé à ce client de ralentir. Cela ne dit rien de
l'existence de la recette. Attendez et redemandez, ou augmentez WB_MIN_INTERVAL_MS.
not_found — la passerelle a répondu, et il n'y a aucune page à cette adresse. Cherchez le
nom plutôt que de deviner la clé.
Une recherche renvoie moins de lignes que demandé — le Cookbook partage son wiki avec tous
les autres livres de Wikibooks, et les lignes venues d'ailleurs sont écartées. Les notes disent
combien.
Une recette revient sans ingrédients — la page porte peut-être sur un ingrédient ou une
technique plutôt que sur une recette. Les listes comme les tableaux d'ingrédients sont lus, donc
une réponse vide signifie que la page énonce ses ingrédients ailleurs. Les notes le disent ;
suivez l'url, et notez qu'aucune remise à l'échelle n'est rapportée pour une page qui n'a
livré aucune quantité.
parse_failure — la passerelle a répondu dans une forme que ce serveur ne sait pas lire.
Merci d'ouvrir une issue avec les
arguments utilisés.
Développement
npm install
npm run typecheck
npm test
npm run build
npm run build:fixtures
WB_LIVE=1 npm run test:live
npm run inspector
Les fixtures sont générées et non capturées : aucun contenu du wiki ne vit dans ce dépôt, et la
suite unitaire ne touche jamais au réseau.
La couche d'accès sous src/wikibooks n'importe pas le SDK MCP et est publiée séparément sous
mcp-wikibooks-cookbook/client, utilisable comme simple bibliothèque. L'arithmétique vit sous
src/recipe.
Contribuer
Bugs, questions et idées vont tous dans
le suivi d'issues. Les pull
requests sont bienvenues ; ouvrez d'abord une issue, pour qu'on s'accorde sur la bonne réponse
avant que vous n'écriviez le code. CONTRIBUTING.md donne le détail, et
SECURITY.md couvre tout ce qui est exploitable.
Soutenir
Gratuit, et ça le reste. Si ça vous a fait gagner du temps, vous pouvez
m'offrir un café.
Licence
MIT. Voir LICENSE. Cette licence couvre le code source seul, pas les recettes
récupérées à travers lui, publiées sous Creative Commons Attribution-Partage dans les mêmes
conditions 4.0 et porteuses des obligations que cette licence attache.
Projet non officiel, sans affiliation à Wikimedia ni à la communauté Wikibooks, et sans
approbation de leur part.