cookidoo-mcp

An MCP server for Cookidoo, built with NestJS. It exposes a Cookidoo account (recipes, shopping list, subscription) to AI tools (Claude, IDEs, agents, …) as a set of MCP tools.

The Cookidoo client is a TypeScript rewrite of the Python cookidoo-api library. This first migration covers the core: authentication, account info, recipe search & details, and shopping-list management.

Architecture

The project follows the same DDD + CQRS + Hexagonal layout as gardenia-api:

src/
  core/
    config/            env validation + Cookidoo config (env-var credentials)
    mcp/               shared MCP transport (Streamable HTTP) + tool discovery
  contexts/
    cookidoo/
      domain/          types, the ICookidooClient port, exceptions
      application/     CQRS commands & queries (dispatch to the port)
      infrastructure/  CookidooHttpClient — the TS rewrite of cookidoo-api
      transport/mcp/   MCP tools + Zod input schemas
  app.module.ts
  main.ts

• Transport: Streamable HTTP (stateless) at POST /api/mcp. GET/DELETE return 405 (no sessions). A fresh McpServer is built per request.

• Tools live in contexts/cookidoo/transport/mcp/ and only dispatch Commands/Queries through the CQRS bus — never call the client directly.

• The client (CookidooHttpClient) is a singleton behind the COOKIDOO_CLIENT port. It logs in lazily via the Cookidoo OAuth2 cookie flow and transparently re-authenticates on a 401.

Related MCP server: cookwith-mcp

Configuration

Credentials and localization come from environment variables (see .env.example):

Running

Local (pnpm)

pnpm install
cp .env.example .env   # then fill in your credentials
pnpm dev               # watch mode
# or
pnpm build && pnpm prod

Docker

docker build -t cookidoo-mcp .

With an env file:

cp .env.example .env   # then fill in your credentials
docker run --rm -p 3000:3000 --env-file .env cookidoo-mcp

Or pass variables directly:

docker run --rm -p 3000:3000 \
  -e COOKIDOO_EMAIL=your@email.com \
  -e COOKIDOO_PASSWORD=your-password \
  cookidoo-mcp

Optional localization and port overrides work the same way (-e PORT=3010, -e COOKIDOO_COUNTRY_CODE=es, etc.).

If you set a custom PORT, map the same port on the host and in the container (e.g. -p 3010:3010 when PORT=3010).

The MCP endpoint is then available at http://localhost:3000/api/mcp (or your custom port).

Cursor

Cookidoo credentials live in the server .env — Cursor only needs the HTTP endpoint. The server must be running (pnpm dev or pnpm prod) before Cursor connects.

1. Copy .cursor/mcp.json.example to .cursor/mcp.json.

2. If you changed PORT in .env, update the URL port to match (default 3000).

3. Restart Cursor (Settings → Tools & MCP should list cookidoo).

Authentication is handled by the NestJS process via COOKIDOO_EMAIL / COOKIDOO_PASSWORD; do not put Cookidoo credentials in mcp.json.

Tools

Adding a tool

1. Add a Zod input schema under transport/mcp/schemas/.

2. Add a Command/Query (+ handler) under application/ that dispatches to the ICookidooClient port; extend the port + CookidooHttpClient if the underlying Cookidoo endpoint isn't wired yet.

3. Add the tool under transport/mcp/tools/, tagged with @McpTool(), and register it in the MCP_TOOLS array of cookidoo.module.ts.

Not yet migrated

The upstream library also covers custom recipes, collections (managed/custom) and the meal-planning calendar. These are intentionally left out of this first "core" migration and can be added following the steps above.

License

UNLICENSED — © Sisques Labs.