# HowToCook-mcp: a recipe MCP server for AI assistants

> HowToCook-mcp is a TypeScript Model Context Protocol server that exposes a Chinese home cooking recipe collection to an AI assistant, with five tools covering recipe listing, category filtering, single recipe lookup, weekly meal planning with allergies and dislikes, and a random menu suggestion. It runs over stdio, HTTP or SSE, and ships as an npm package, a Docker image and a DXT desktop extension.

**worryzyy/HowToCook-mcp** — 基于Anduin2017 / HowToCook （程序员在家做饭指南）的mcp server

- Repository: https://github.com/worryzyy/HowToCook-mcp
- Stars: 785 · Forks: 60
- Language: TypeScript
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/worryzyy-howtocook-mcp

## What the server exposes and where the data comes from

HowToCook-mcp is an MCP server built on top of the HowToCook project, which is described in the repository as a guide for programmers cooking at home. The data source is that collection, and the documentation is clear that the server is a wrapper around it rather than a new dataset.

That framing is the whole design. The hard part of a recipe MCP server is not the protocol, it is having a corpus of recipes in a consistent, machine-readable form, and HowToCook supplies that. The repository carries it as a single file, all_recipes.json, which is bundled with the npm package and copied into the container image, and the Dockerfile has a comment noting that the code resolves it relative to the build directory, so it sits at the root of the app in the image.

The five tools are the interesting part. One retrieves all available recipes, and a warning is attached to it that the context is too large, which is an honest admission that a tool returning an entire corpus is a bad tool. The others filter by category, look up one recipe by name with its ingredients and steps, plan a week of meals given allergies, disliked ingredients and a number of people, and pick a menu for a given number of people when the user cannot decide.

The meal planning and random menu tools take structured parameters rather than free text, and that matters. Allergies is a list, avoid items is a list, and the number of people is a bounded range from one to ten. A client can therefore pass structured constraints and get a plan that respects them, rather than hoping the model parses a sentence correctly.

## The three transports and the command line

The server supports three transports, selected by a command line argument, and the choice is what makes it usable from more than one kind of client.

The `--transport` argument takes stdio, http or sse, with stdio as the default. The `--port` argument sets the listening port for the http and sse transports, defaulting to 3000.

```bash
node build/index.js --transport http --port 8080
```

The stdio default is the one that matters for desktop MCP clients, where the client launches the server as a child process and talks to it over its standard input and output. The HTTP and SSE modes are the ones for a shared or containerised deployment, and the package.json has a script for each combination of start and dev, so start:stdio, start:http and start:sse are all one command away.

The project also runs as an HTTP service in Docker. The compose file maps port 3000 to the host, with a comment in Chinese explaining that you change the left side if 3000 is taken, and it includes a healthcheck that fetches a health endpoint and exits accordingly, on a thirty second interval with a three second timeout and three retries.

The Docker image is a two stage build on node 22 alpine. The builder installs with npm ci, compiles the TypeScript, and the runtime stage installs only production dependencies with npm ci and omit=dev, copies the compiled build across, copies the recipe data in, and runs as the non-root node user with port 3000 exposed. The default command starts the server in HTTP mode, and the comment notes that the stdio mode is invoked with docker run -i and the transport argument.

## Installing it and wiring it into a client

The prerequisites are Node.js 16.0.0 or newer and npm or yarn, and the local install is three steps.

```bash
git clone https://github.com/worryzyy/howtocook-mcp.git
cd howtocook-mcp
```

```bash
npm install
```

```bash
npm run build
```

The build is a plain tsc invocation, the start script runs node build/index.js, and the dev scripts compile and start in one step, which is convenient when you are changing a tool.

The client configuration is the standard MCP server block. For a published package, the command is npx with the package name.

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

And for a clone you have built locally, the command is node pointing at the compiled entry point.

```json
{
  "mcpServers": {
    "howtocook-mcp": {
      "command": "node",
      "args": ["youpath\\howtocook-mcp\\build\\index.js"]
    }
  }
}
```

The documentation calls out a specific failure, that the npx form needs the package installed globally first with npm i -g howtocook-mcp or you will get a Failed to create client error. The supported clients listed are the Claude desktop application, Cursor and any other client that speaks MCP, and the general guidance for other clients is to specify the server name and the npx command.

The package is published to npm as howtocook-mcp, at version 0.2.2, with a bin entry pointing at the built entry point so it can be launched as a command.

## The DXT desktop extension route

Alongside the standard MCP distribution, the project offers a DXT package, the Desktop Extensions format, so the server can be installed into Claude Desktop with a click rather than configured by hand.

The documentation asks you to make sure you have the latest Claude Desktop, and says the DXT file for the current MCP has been uploaded to the repository and can be downloaded directly or built yourself from a fork. The extension is packaged in the repository as HowToCook-mcp.dxt alongside a manifest.json.

Building one locally is a three step process with the dxt tooling. You install the CLI globally with npm install -g @anthropic-ai/dxt. Then in the folder containing your local MCP server, which the documentation describes as the root directory of your MCP, you run dxt init, which guides you through creating a manifest.json. And then dxt pack creates the dxt file.

The documentation explains what the result is for: any application that supports DXT can now run your local MCP server, and opening the file with Claude on macOS or Windows shows an install dialog. The reference for the format is the anthropics/dxt repository.

This matters for the audience of the project, because the two supported clients are configured in completely different ways. A client that speaks MCP over a subprocess needs the JSON configuration, while a Claude user who just wants the recipe tools can take the dxt file.

## The dependency set and what it tells you

The package.json is short and the runtime dependencies are the interesting part.

The Model Context Protocol SDK at 1.9.0 or later provides the server framework and the tool definitions. Express 5 provides the HTTP and SSE transports, which is why the express dependency and the @types/express development dependency are both there. Commander 14 handles the command line arguments, which is the `--transport` and `--port` parsing, and zod at 3.22 validates the tool inputs, which is how the structured parameters for allergies, avoided items and the people count are checked at the boundary.

That last one is the design decision worth noticing. The tool schemas in an MCP server are described to the client so the model knows what to send, and zod gives the server a way to enforce the same schema on what arrives. It is why the tools can take a list of allergies and a bounded people count and rely on it, rather than parsing free text.

The package is an ES module, with the type field set to module, and the build output is CommonJS in build/index.js, which is what the bin entry and the Docker command both point at. The published files are the build directory, the recipe data and the project readme file, so the source is not shipped. The publish configuration sets the registry to npmjs and the access to public, and the scripts include patch, minor and major publish targets driven by npm version.

One discrepancy is worth flagging. The package.json declares the licence as ISC, while the project documentation's licence section says MIT License, and the licence field on the repository says no licence identifier. For a package published to a public registry, that inconsistency is the first thing to fix before you build on it.

## Where HowToCook-mcp is the wrong choice

The first limitation is the size of the all-recipes tool. The documentation itself warns against using it because the context is too large, and a tool that returns an entire corpus of recipes will overwhelm the context window of the model that called it. The other four tools are the ones to reach for, and a client that lets the model pick a tool can end up on the wrong one.

The second is the data model. The recipes are a JSON file with no schema in this repository, and there is no database, no ingredient normalisation, no nutrition information, no serving scaling and no shopping list. A kitchen application that wants any of those is building them, and the server gives it no help.

The third is that the data is somebody else's. The documentation is explicit that the data comes from the HowToCook project, and it asks readers to star that project. A server that republishes a collection under a different licence is a licensing question that this repository does not answer, and the answer is the upstream project's terms rather than the MIT or ISC statement here.

The fourth is the release cadence. The recent releases section says there are no GitHub releases, the package version is 0.2.2, and the last push was on 2026-07-08. A server that has to track an upstream data collection needs to be updated when that collection changes, and a package versioned below 1.0 with no release history gives you little to pin.

The fifth is that the transports and the tools are simple enough to rebuild. A single JSON file and five tools over an SDK is a small amount of code, and if your needs differ in any of the ways above, writing the server yourself against the same SDK is likely faster than adapting this one.

## HowToCook-mcp compared with a hosted recipe API and with a plain file of recipes

The comparison with a hosted recipe API is the one most developers will have considered first, and the difference in approach is data ownership and scale. A hosted API has a real database, a real search index, a schema, a maintenance team and a bill, and it can answer questions about a million recipes. This server has a JSON file that ships inside the npm package, so it is as complete as the upstream collection and no more, and it is free and offline.

For an assistant that needs to answer what to cook tonight from a known corpus, that is enough. For anything that needs to search a catalogue, scale, or stay current, it is not.

The second comparison is with just giving the model the recipe file. This is the honest baseline, and it is nearly the same thing. A model with a handful of recipes pasted into the conversation can answer questions about them, and the MCP server's value is that the corpus is available on demand and the tools do the filtering, so the model does not have to hold the whole collection in context.

That is exactly why the all-recipes tool is the weak one, and why the category filter and the single recipe lookup are the useful ones. A tool that returns one recipe, or one category, is a tool that fits in a context window.

The third comparison is with the reverse arrangement, where the model calls a hosted API to fetch recipes. The difference is that the data does not have to leave the machine, and there is no API key to manage, which for a personal assistant setup is a genuine simplification.

The fourth is with the DXT route, which is a distribution difference rather than a functional one. The same tools reach a user as a JSON configuration for a technical client or as a double-clickable file for a Claude Desktop user.

## Licence, project state and what to check before you build on it

The licence position needs resolving first. The licence field on the repository says no licence identifier, the project documentation says it is under the MIT License, and the package.json says ISC. Those are different licences with different terms, and the one that governs the published package is the one in the package metadata, because that is what npm and every package scanner read. A discrepancy like that is a small fix and a serious problem to discover later.

Beneath that, the data question matters more. The recipe collection is the substance of this project, and the server is the wrapper. What the upstream HowToCook project licenses its content under, and whether that permits redistribution inside an npm package and inside a container image, is the question to ask before shipping anything based on it.

The project is not archived and the last push was on 2026-07-08, so it is being worked on, and the package version is 0.2.2. The repository has a Dockerfile and a docker-compose.yml for the HTTP mode, a manifest.json and a prebuilt HowToCook-mcp.dxt for the desktop extension, a public/ directory holding the extension assets including the images the documentation shows, and a src/ directory with the TypeScript sources alongside a tsconfig.json.

Four things to check before you rely on it.

The two licences, and reconcile them before the package is depended on by anything.

The upstream data licence, and whether the npm redistribution and the Docker image are both covered by it.

The context behaviour of the all-recipes tool in your client, and if it is too large, whether your client can be configured to discourage it, since the documentation flags it as the one to avoid.

And the people count bound, because the tool takes one to ten people, so a request for a party of twenty is out of range and the client will get a validation error rather than a plan.

## Conclusion

HowToCook-mcp suits a developer who wants to point an MCP client at an existing recipe dataset rather than write a server, and who wants the stdio, HTTP and SSE transports already implemented. It is the wrong tool for a kitchen application that needs nutrition data, shopping lists or a real database, since the data is a single JSON file bundled with the package, and it is the wrong choice for a production service, since the licence declared in the package metadata is ISC while the project documentation says MIT. Before publishing anything based on it, reconcile those two licence statements and check how the upstream recipe collection is licensed, because the data is the substance here rather than the server.

## FAQ

### What is HowToCook-mcp?

It is a Model Context Protocol server written in TypeScript that exposes the HowToCook collection of home cooking recipes to an AI assistant. It offers five tools covering all recipes, recipes by category, a single recipe by name, weekly meal planning with allergies and dislikes, and a random menu for a number of people.

### How do I install and run HowToCook-mcp?

You need Node.js 16 or newer and npm or yarn. Clone the repository, run npm install, then npm run build, and start it with npm start. The package is also published to npm as howtocook-mcp, so a client can launch it with npx -y howtocook-mcp.

### Which transports does HowToCook-mcp support?

Three, selected with the --transport argument: stdio, which is the default and the one desktop MCP clients use, and http and sse, which take a --port argument defaulting to 3000. The package.json has start and dev scripts for each of the three.

### What is the DXT file in the HowToCook-mcp repository?

It is a Desktop Extensions package so the server can be installed into Claude Desktop with a click. You need the latest Claude Desktop, the prebuilt file is in the repository, and you can build your own with npm install -g @anthropic-ai/dxt, then dxt init in your MCP root directory to create a manifest.json, and dxt pack to produce the file.

### What parameters does the HowToCook-mcp meal planning tool take?

An allergies list, an avoidItems list of disliked ingredients, and a peopleCount between one and ten. The random menu tool takes only the number of people, and the category tool takes a category such as seafood, breakfast, meat or staple food.

### What licence is HowToCook-mcp released under?

The README says MIT while the package metadata says ISC and the repository records no identifier, so the statements disagree and the package metadata is the one that governs the published package. The recipe data itself comes from the separate HowToCook project and carries its own terms.

## Sources

- [Issues](https://github.com/worryzyy/HowToCook-mcp/issues)
- [README](https://github.com/worryzyy/HowToCook-mcp/blob/master/README.md)
- [worryzyy/HowToCook-mcp on GitHub](https://github.com/worryzyy/HowToCook-mcp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/worryzyy-howtocook-mcp