mcp-marmiton

# mcp-marmiton

[![npm](https://img.shields.io/npm/v/mcp-marmiton.svg)](https://www.npmjs.com/package/mcp-marmiton)
[![CI](https://github.com/smeet666/mcp-marmiton/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-marmiton/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-marmiton.svg)](./LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-marmiton)

An [MCP](https://modelcontextprotocol.io) server for [Marmiton](https://www.marmiton.org),
the French recipe site. Search recipes, read their ingredients and steps, and
**rescale the quantities to any number of servings**. **No API key, no account, no
configuration.**

_(Version française plus bas / [French version below](#mcp-marmiton-français))_

---

## Quickstart

**One-click install**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=marmiton&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tYXJtaXRvbiJdfQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=marmiton&config=%7B%22name%22%3A%22marmiton%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-marmiton%22%5D%7D)

**Claude Code**

```bash
claude mcp add marmiton -- npx -y mcp-marmiton
```

**Claude Desktop, Cursor, and any client using the standard config format**

```json
{
  "mcpServers": {
    "marmiton": {
      "command": "npx",
      "args": ["-y", "mcp-marmiton"]
    }
  }
}
```

## Tools

| Tool                | What it does                           | Key parameters                                          |
| ------------------- | -------------------------------------- | ------------------------------------------------------- |
| `search_recipes`    | Finds recipes by dish or ingredient.   | `query`, `limit`                                        |
| `get_recipe`        | Reads one recipe, optionally rescaled. | `id`, `url`, `servings`                                 |
| `scale_ingredients` | Rescales any ingredient list, offline. | `ingredients`, `factor`, `from_servings`, `to_servings` |

Search returns a Marmiton `id` for every result; `get_recipe` takes that id. That
is the intended chain: search, then read.

The server is **read-only**. It never posts anything to Marmiton.

### Scaling is the point

Asking a language model to divide a recipe by 1.5 tends to produce "2.4 eggs" and
"0.67 pinches of salt", stated with the same confidence as a correct number. This
server does the arithmetic itself and, more importantly, **says what it could not
compute**. Every ingredient comes back with a `scaling` flag:

| Flag       | Meaning                                          | Example at factor 0.667           |
| ---------- | ------------------------------------------------ | --------------------------------- |
| `scaled`   | Multiplied and rounded to a readable value.      | `25 cl de lait` → `17 cl de lait` |
| `rounded`  | Multiplied, then rounded to something countable. | `3 oeufs` → `2 oeufs`             |
| `unscaled` | Left exactly as published.                       | `1 pincée de sel`, `coriandre`    |

Two rules are enforced. Scaling a recipe **down never asks for more** than the
original: half a sachet at factor 0.667 becomes a third of a sachet, never a whole
one. And scaling never **silently drops** an ingredient by rounding it to zero,
which is why small amounts come back as fractions.

`scale_ingredients` exposes the same logic **without any network request**, so it
also works on a recipe pasted from somewhere else.

### Other things worth knowing

**Marmiton is French.** Queries work best in French: `tarte aux pommes`,
`poulet curry coco`.

**One page of results.** Marmiton's robots.txt disallows paginating search
results, so this server does not, and there is no page parameter. Narrow the query
instead.

**Nutrition is not rescaled.** The figures Marmiton publishes describe the recipe
as written, and they are returned as such.

**Structured data, not scraping.** Everything is read from the `schema.org`
JSON-LD that Marmiton publishes for machines, so there are no CSS selectors to
break when the site is redesigned.

## Configuration

Every variable is optional. Set them in the `env` block of your MCP client config.

| Variable                     | Default                                | Purpose                                                        |
| ---------------------------- | -------------------------------------- | -------------------------------------------------------------- |
| `MARMITON_USER_AGENT`        | `mcp-marmiton v<version> (<repo url>)` | User-Agent sent to Marmiton.                                   |
| `MARMITON_MIN_INTERVAL_MS`   | `1000`                                 | Minimum gap between requests. Values below 500 ms are ignored. |
| `MARMITON_TIMEOUT_MS`        | `15000`                                | Per-request timeout.                                           |
| `MARMITON_MAX_RETRIES`       | `3`                                    | Retries on rate limiting and transient errors.                 |
| `MARMITON_CACHE_TTL_MS`      | `900000`                               | In-memory cache lifetime (15 minutes).                         |
| `MARMITON_CACHE_MAX_ENTRIES` | `200`                                  | In-memory cache size.                                          |
| `MARMITON_LOG_LEVEL`         | `error`                                | `silent`, `error`, `info` or `debug`. Logs go to stderr.       |

## Troubleshooting

**`rate_limited` errors.** Marmiton is throttling this client. The server already
retries with backoff and slows itself down. Wait a moment and try again, and raise
`MARMITON_MIN_INTERVAL_MS` if it persists. This never means the recipe is missing.

**`parse_failure` errors.** Marmiton changed how it publishes its structured data
and the server could not read the response. Please
[open an issue](https://github.com/smeet666/mcp-marmiton/issues) with the recipe
you asked for. The server reports this loudly rather than pretending it found
nothing.

## Development

```bash
npm install
npm run build:fixtures   # regenerate the HTML test fixtures
npm test                 # unit tests, no network
npm run typecheck
npm run build
MARMITON_LIVE=1 npm run test:live   # hits the real site, excluded from CI
npm run inspector        # explore the tools in the MCP Inspector
```

Fixtures are generated, not captured: they reproduce Marmiton's JSON-LD shape with
invented recipes, so the tests are deterministic and no Marmiton content lives in
this repository.

The scraping layer (`src/marmiton`, `src/recipe`) does not import the MCP SDK and
is published separately as `mcp-marmiton/client`, so it can be used as a plain
library.

## Recipes, copyright and cooking

Ingredient lists and cooking steps are facts and procedures. The descriptive prose
an author writes around them is their work, and this server does not return it:
you get what you need to cook, plus a link to the original page.

This server is a client. It reads the structured data Marmiton publishes for
machines, on demand, one request at a time, in response to an explicit request
from you or your assistant. It does not crawl the site, does not build a recipe
database, and writes nothing to disk. It honours Marmiton's robots.txt, including
the rule against paginating search results.

Every result carries the recipe title and its source URL. If you display or reuse
anything this server returns, keep that attribution and link back to Marmiton.

Rescaled quantities are computed, and cooking is not arithmetic: baking in
particular does not always scale linearly. Read them as a helpful starting point
and use your judgement.

This is an unofficial project, with no affiliation to or endorsement by Marmiton.

## License

MIT. See [LICENSE](./LICENSE). The license covers this source code only, not the
recipes retrieved through it.

---

<a name="mcp-marmiton-français"></a>

# mcp-marmiton (français)

Un serveur [MCP](https://modelcontextprotocol.io) pour [Marmiton](https://www.marmiton.org).
Cherchez des recettes, lisez leurs ingrédients et leurs étapes, et **adaptez les
quantités au nombre de convives**. **Sans clé d'API, sans compte, sans configuration.**

## Démarrage rapide

**Installation en un clic**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=marmiton&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1tYXJtaXRvbiJdfQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=marmiton&config=%7B%22name%22%3A%22marmiton%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-marmiton%22%5D%7D)

**Claude Code**

```bash
claude mcp add marmiton -- npx -y mcp-marmiton
```

**Claude Desktop, Cursor, et tout client utilisant le format standard**

```json
{
  "mcpServers": {
    "marmiton": {
      "command": "npx",
      "args": ["-y", "mcp-marmiton"]
    }
  }
}
```

## Outils

| Outil               | Rôle                                        | Paramètres principaux                                   |
| ------------------- | ------------------------------------------- | ------------------------------------------------------- |
| `search_recipes`    | Trouve des recettes par plat ou ingrédient. | `query`, `limit`                                        |
| `get_recipe`        | Lit une recette, avec adaptation possible.  | `id`, `url`, `servings`                                 |
| `scale_ingredients` | Adapte n'importe quelle liste, hors ligne.  | `ingredients`, `factor`, `from_servings`, `to_servings` |

La recher