kitchenowl-mcp

An MCP server for KitchenOwl, built with FastMCP. It lets AI assistants (Claude, or any MCP client) manage your shopping lists, recipes, meal plan, and shared expenses over KitchenOwl's REST API.

It runs as a standalone service with streamable HTTP transport — typically as a Docker container next to your KitchenOwl instance. It is independent of KitchenOwl's built-in /api/mcp endpoint and also works with older KitchenOwl servers.

Quick start (Docker Compose)

cp .env.example .env      # fill in KITCHENOWL_TOKEN (and JWT_SECRET_KEY for the bundled KitchenOwl)
docker compose up -d

The MCP endpoint is then available at http://localhost:8000/mcp.

If you already run KitchenOwl elsewhere, only build/run the kitchenowl-mcp service and point KITCHENOWL_URL at your instance.

Configuration

Env var	Required	Default	Description
KITCHENOWL_URL	yes	—	Base URL of your KitchenOwl instance (no trailing /api)
KITCHENOWL_TOKEN	yes	—	Long-lived token of the KitchenOwl user to act as
KITCHENOWL_HOUSEHOLD_ID	no	auto	Default household; auto-picked when the user has exactly one
MCP_HOST / MCP_PORT / MCP_PATH	no	0.0.0.0 / 8000 / /mcp	Where the MCP HTTP endpoint listens
MCP_SERVER_TOKEN	no	unset	If set, MCP clients must send Authorization: Bearer <token>

Getting a long-lived token

In the KitchenOwl app: Profile → Sessions → create a long-lived token, or via the API:

# 1. Log in (returns a short-lived access_token)
curl -X POST "$KITCHENOWL_URL/api/auth" -H 'Content-Type: application/json' \
     -d '{"username":"you","password":"your-password"}'

# 2. Mint a long-lived token with it
curl -X POST "$KITCHENOWL_URL/api/auth/llt" \
     -H "Authorization: Bearer <access_token>" \
     -H 'Content-Type: application/json' -d '{"device":"kitchenowl-mcp"}'

Connecting a client

• Claude Code: claude mcp add --transport http kitchenowl http://localhost:8000/mcp
• Claude Desktop / claude.ai custom connector: add a remote MCP server with the URL https://<your-host>/mcp (must be HTTPS-reachable; put a reverse proxy in front)
• MCP Inspector: npx @modelcontextprotocol/inspector, connect to http://localhost:8000/mcp (streamable HTTP)

If MCP_SERVER_TOKEN is set, configure the client to send it as a bearer token.

Tools

All household-scoped tools take an optional household_id; with a single household (or KITCHENOWL_HOUSEHOLD_ID set) it can be omitted.

Households — list_households, get_household (includes member ids for expenses)

Shopping lists — list_shopping_lists, create_shopping_list, rename_shopping_list, delete_shopping_list, get_shopping_list_items, add_shopping_list_item, update_shopping_list_item, remove_shopping_list_items (batch), get_recent_items, get_suggested_items, add_recipe_items_to_shopping_list, search_items, update_item

KitchenOwl has no check/uncheck state: removing an item means it was purchased and feeds the purchase history and suggestions.

Recipes — list_recipes, search_recipes, get_recipe, create_recipe, update_recipe, delete_recipe, import_recipe_from_url (scrapes a recipe website; returns a draft unless save=true)

Meal planner — get_meal_plan, add_recipe_to_plan, remove_recipe_from_plan, get_recipe_suggestions

Expenses — list_expenses, add_expense, update_expense, delete_expense, get_expense_categories, create_expense_category, get_expense_overview

Security

By default the MCP endpoint is unauthenticated — anyone who can reach it acts as the configured KitchenOwl user. Options, in increasing order of robustness:

1. Keep the port on a trusted network (Docker-internal, LAN, VPN).
2. Set MCP_SERVER_TOKEN to require a bearer token (static token — fine for personal use, not a full auth system).
3. Put a reverse proxy (Caddy/Traefik/nginx) with TLS in front — required anyway for claude.ai remote connectors.

Development

uv sync                                   # install deps (Python >= 3.11)
uv run pytest                             # run the test suite (mocked KitchenOwl API)
uv run ruff check .                       # lint
KITCHENOWL_URL=... KITCHENOWL_TOKEN=... uv run kitchenowl-mcp   # run locally

The tests use FastMCP's in-memory client with a respx-mocked KitchenOwl API, so no running KitchenOwl instance is needed.

Limitations / roadmap

• No item-catalog create/delete tools (add_shopping_list_item creates catalog items implicitly).
• No household create/delete or member management.
• Recipe update_recipe with items/tags replaces the full list (KitchenOwl API semantics).
• KitchenOwl's own experimental MCP endpoint (/api/mcp, recent versions) is an alternative if you don't need a separately deployable server.