๐ณ Kitchen MCP
Your digital kitchen, powered by AI. Track what you have, discover what you can cook, and get guided through every recipe โ step by step, timer by timer.
Whether you're a home cook managing a busy kitchen or a developer building AI-powered cooking assistants, Kitchen MCP gives you the structured foundation to make it real.
๐ What is this?
Kitchen MCP is a local-first Model Context Protocol server that connects an AI assistant to your kitchen. It knows your inventory, your recipes, your equipment, your restrictions, and your preferences โ and it helps you cook better with all of it.
The AI never guesses. The server is always the source of truth.
โจ Features
| Feature | Status | Description |
|---|---|---|
| ๐ฆ Inventory Management | โ | Track food by lot, location, expiry, and state (sealed, opened, cooked, frozen) |
| ๐ Recipe Engine | โ | Create, version, scale, and validate recipes with ingredients, steps, and equipment |
| ๐ฏ Smart Matching | โ | Find the best recipes based on what you have, your restrictions, and your taste |
| ๐จโ๐ณ Cooking Sessions | โ | Start a session, follow guided steps, track ingredient usage, get help when things go wrong |
| โฑ๏ธ Kitchen Timers | โ | Create, pause, resume, and extend timers tied to cooking steps |
| ๐ซ Dietary Restrictions | โ | Set allergies, intolerances, religious and ethical restrictions; server blocks unsafe recipes |
| ๐ถ๏ธ Taste Preferences | โ | Set spice heat, saltiness, sweetness on a 0-10 scale; recipes scored to match |
| ๐ Equipment Catalog | โ | Register stoves, pressure cookers, mixers, refrigerators; server checks compatibility |
| โ๏ธ Unit Conversion | โ | Convert between grams, kilograms, milliliters, teaspoons, tablespoons, cups, and more |
| ๐ Shopping Lists | ๐ | Generate shopping needs from recipes and current inventory |
| ๐ Meal Planning | ๐ | Plan meals for the week based on preferences, expiry, and inventory |
| โฐ Expiry Tracking | ๐ | Get notified before food goes bad, use expiring items first |
๐ Quick Start
๐ Prerequisites
- Node.js >= 20
- npm
โฌ๏ธ Install
git clone https://github.com/craftpip/kitchen-mcp.git
cd kitchen-mcp
npm install
โถ๏ธ Run (stdio)
npm start
๐ Run (HTTP)
npm run dev -- --http
Server listens on http://0.0.0.0:3100/mcp.
๐ณ Docker
docker compose build && docker compose up -d
Data persists in the kitchen-mcp_kitchen-data volume.
๐ค Usage with AI Assistants
Add to your MCP client (like OpenCode, Claude Desktop, etc.):
{
"mcp": {
"kitchen": {
"type": "remote",
"url": "http://localhost:3100/mcp"
}
}
}
Once connected, the AI can:
| Ask | What happens | |
|---|---|---|
| ๐๏ธ | "What do I have?" | Checks inventory, shows what's in stock |
| ๐ฝ๏ธ | "What can I cook for lunch?" | Matches recipes to your inventory and preferences |
| ๐จโ๐ณ | "Start cooking the egg curry" | Creates session, guides through each step |
| โฑ๏ธ | "Set a 10-minute timer" | Creates kitchen timer, tracks it |
| ๐ฆ | "Add 1kg of rice to the pantry" | Adds inventory lot with full tracking |
| ๐ซ | "I'm allergic to peanuts" | Blocks all peanut-containing recipes |
๐ ๏ธ 66 Tools
| Category | ๐ง | What it does |
|---|---|---|
| ๐ System | 2 | Health check, capabilities |
| ๐บ๏ธ Locations | 3 | Rooms, shelves, cabinets, drawers |
| ๐ฅ Ingredients | 4 | Catalog, aliases, search |
| ๐ฆ Inventory | 7 | Lots, transactions, expiry tracking |
| ๐ Equipment | 6 | Appliances, calibration, availability |
| โ๏ธ Measurements | 3 | Unit conversion, household containers |
| ๐ Recipes | 9 | CRUD, versioning, scaling, availability |
| ๐ซ Restrictions | 3 | Allergies, intolerances, dietary rules |
| ๐ถ๏ธ Preferences | 3 | Spice heat, saltiness, sweetness |
| ๐ฏ Matching | 1 | Recipe scoring engine |
| ๐จโ๐ณ Sessions | 16 | Cooking lifecycle, step tracking |
| โฑ๏ธ Timers | 9 | Kitchen timers with full control |
๐๏ธ Architecture
Kitchen MCP follows a strict principle: the server is the authority.
- ๐๏ธ SQLite with WAL mode for reliability
- ๐ All state changes go through structured tools
- ๐ Recipe versions are immutable once used in sessions
- ๐ฆ Inventory deductions happen via transactions, never direct overwrites
- ๐ Every action is audit-logged
The AI interprets natural language, picks the right tools, and explains results. The server stores facts, validates requests, and enforces rules. Neither side does the other's job.
๐งโ๐ป Development
# Typecheck
npx tsc --noEmit
# Build
npm run build
# Test
npm test
# Dev (HTTP mode)
npm run dev -- --http
๐ Project Structure
src/
โโโ ๐ ๏ธ server/tools/ # 13 tool files, 66 tools
โโโ ๐๏ธ domain/ # Services and types per domain
โโโ โ๏ธ infrastructure/ # Database, audit, idempotency, logging
โโโ ๐ฆ shared/ # Response envelope, errors, IDs, time
๐ License
MIT
