cookidoo-mcp
Model Context Protocol · NestJS Model Context Protocol · NestJS

Your Cookidoo
account, for AI. Tu cuenta de Cookidoo,
para la IA.

An MCP server that exposes your Cookidoo recipes, shopping list, meal planner and collections to Claude, IDEs and any AI agent — as a clean set of typed tools. Un servidor MCP que expone tus recetas de Cookidoo, la lista de la compra, el planificador de menús y las colecciones a Claude, IDEs y cualquier agente de IA — como un conjunto de herramientas tipadas.

Get startedEmpezar GitHub
36
MCP toolsHerramientas MCP
6
Tool domainsDominios
100%
TypeScriptTypeScript
DDD
CQRS · HexagonalCQRS · Hexagonal
What it doesQué hace

Everything in your kitchen, scriptable.Toda tu cocina, programable.

cookidoo-mcp is a TypeScript rewrite of the Python cookidoo-api, wrapped as an MCP server so any AI client can read and act on your account. cookidoo-mcp es una reescritura en TypeScript del cookidoo-api de Python, empaquetada como servidor MCP para que cualquier cliente de IA lea y actúe sobre tu cuenta.

🔎

Recipe searchBúsqueda de recetas

Search the catalogue with filters and pull full recipe details by id.Busca en el catálogo con filtros y obtén los detalles completos de una receta por id.

🛒

Shopping listLista de la compra

Add or remove recipe ingredients and free-text items, mark them as bought, rename or clear the list.Añade o quita ingredientes y artículos libres, márcalos como comprados, renómbralos o vacía la lista.

📅

Meal plannerPlanificador

Read a week of the calendar and schedule recipes — standard or custom — on any day.Lee una semana del calendario y planifica recetas — estándar o personalizadas — en cualquier día.

📒

Custom recipesRecetas propias

List, read, create and delete your own recipes derived from existing ones.Lista, consulta, crea y elimina tus propias recetas derivadas de otras existentes.

📚

CollectionsColecciones

Browse and manage both managed (subscribed) and custom collections, paged.Explora y gestiona colecciones gestionadas (suscritas) y propias, paginadas.

🔐

Lazy, self-healing authAuth perezosa y auto-reparable

Logs in via the Cookidoo OAuth2 cookie flow, re-authenticates on a 401, with optional session persistence.Inicia sesión por el flujo OAuth2 de Cookidoo, se reautentica ante un 401, con persistencia de sesión opcional.

Under the hoodPor dentro

Clean architecture, by design.Arquitectura limpia, por diseño.

Built with NestJS following a DDD + CQRS + Hexagonal layout. Tools never touch the HTTP client directly — they dispatch Commands and Queries through a bus. Hecho con NestJS siguiendo un diseño DDD + CQRS + Hexagonal. Las herramientas nunca tocan el cliente HTTP directamente — despachan Comandos y Consultas por un bus.

  • 1

    TransportTransporte

    Stateless Streamable HTTP at POST /api/mcp. A fresh McpServer is built per request; GET/DELETE return 405.Streamable HTTP sin estado en POST /api/mcp. Se construye un McpServer nuevo por petición; GET/DELETE devuelven 405.

  • 2

    Tools layerCapa de herramientas

    Each tool has a Zod input schema and only dispatches a Command or Query — never calls the client.Cada herramienta tiene un esquema de entrada Zod y solo despacha un Comando o Consulta — nunca llama al cliente.

  • 3

    Application (CQRS)Aplicación (CQRS)

    Commands and Queries with handlers that talk to the ICookidooClient port.Comandos y Consultas con manejadores que hablan con el puerto ICookidooClient.

  • 4

    InfrastructureInfraestructura

    CookidooHttpClient — a singleton behind the port — implements the TS rewrite of cookidoo-api with lazy OAuth2 login.CookidooHttpClient — un singleton tras el puerto — implementa la reescritura TS de cookidoo-api con login OAuth2 perezoso.

src/
# DDD + CQRS + Hexagonal
src/
  core/
    config/      # env validation + creds
    mcp/         # Streamable HTTP transport
  contexts/
    cookidoo/
      domain/          # types, ICookidooClient port
      application/     # CQRS commands & queries
      infrastructure/  # CookidooHttpClient
      transport/mcp/   # tools + Zod schemas
  app.module.ts
  main.ts
QuickstartInicio rápido

Up and running in minutes.Funcionando en minutos.

Run it locally with pnpm, or as a container with Docker. Requires Node and a Cookidoo account.Ejecútalo localmente con pnpm, o como contenedor con Docker. Requiere Node y una cuenta de Cookidoo.

1

Install & configure credentialsInstala y configura las credenciales

bash
pnpm install
cp .env.example .env   # then fill in your credentials
2

Run in watch mode (or production)Ejecuta en modo watch (o producción)

bash
pnpm dev               # watch mode
# or
pnpm build && pnpm prod
3

Or run it with DockerO ejecútalo con Docker

bash
docker build -t cookidoo-mcp .
docker run --rm -p 3000:3000 --env-file .env cookidoo-mcp
4

Point your MCP client at itApunta tu cliente MCP

endpoint
POST http://localhost:3000/api/mcp    # Streamable HTTP (stateless)
GET  http://localhost:3000/api/health # liveness probe
ConfigurationConfiguración

Configured by environment.Configurado por entorno.

Credentials and localization come from environment variables. See .env.example in the repo.Las credenciales y la localización vienen de variables de entorno. Mira .env.example en el repo.

VariableVariable RequiredObligatoria DefaultPor defecto DescriptionDescripción
COOKIDOO_EMAILyessí—Cookidoo account emailEmail de la cuenta de Cookidoo
COOKIDOO_PASSWORDyessí—Cookidoo account passwordContraseña de la cuenta de Cookidoo
COOKIDOO_COUNTRY_CODEnonoesLocalization country codeCódigo de país de localización
COOKIDOO_LANGUAGEnonoes-ESLocalization languageIdioma de localización
COOKIDOO_URLnonocookidoo.es/…Localization base URLURL base de localización
COOKIDOO_COOKIE_FILEnono—Path to persist the session across restartsRuta para persistir la sesión entre reinicios
COOKIDOO_DEBUGnonofalseLog the full OAuth2 login flow to debug authenticationRegistra todo el flujo de login OAuth2 para depurar la autenticación
PORTnono3000HTTP portPuerto HTTP
🔒
By default the session lives only in memory. Set COOKIDOO_COOKIE_FILE to a writable path to restore and rewrite the session across restarts — an expired one self-heals on the next 401. The file holds session cookies: treat it like a credential and keep it out of version control. Por defecto la sesión vive solo en memoria. Define COOKIDOO_COOKIE_FILE con una ruta escribible para restaurar y reescribir la sesión entre reinicios — una caducada se auto-repara en el siguiente 401. El archivo guarda cookies de sesión: trátalo como una credencial y mantenlo fuera del control de versiones.
ReferenceReferencia

36 MCP tools, fully typed.36 herramientas MCP, totalmente tipadas.

Every tool dispatches a Command or Query through the CQRS bus. Filter by domain below.Cada herramienta despacha un Comando o Consulta por el bus CQRS. Filtra por dominio abajo.