Model Context Protocol (MCP) server that exposes CocktailPi backend operations as MCP tools.
This README focuses on getting it running fast for end users.
This MCP server is started on demand by your AI client (stdio).
You do not run this as a long-lived container with docker compose up -d.
Before connecting AI, make sure your CocktailPi backend is reachable from Docker.
You need:
- A working CocktailPi installation
- A backend URL (for example
http://cocktailpi/,http://localhost:8080, or your Tailscale/LAN URL) - Credentials or a JWT token
Most MCP clients accept an mcpServers command-based config.
Important: this server uses stdio transport, so your AI client launches the command and communicates over that process's stdin/stdout.
Use these values in the command args:
COCKTAILPI_BASE_URL: your CocktailPi backend URL- Option A:
COCKTAILPI_USERNAME+COCKTAILPI_PASSWORD - Option B:
COCKTAILPI_ACCESS_TOKEN(instead of username/password) - Optional:
COCKTAILPI_TIMEOUT_SECONDS=20
The server command is the same across MCP clients. Only the config file path changes.
Config file locations:
- Claude Desktop (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json - Cursor:
.cursor/mcp.json - Other MCP clients: use the client's
mcpServersconfig file
Use this config block:
{
"mcpServers": {
"cocktailpi": {
"command": "docker",
"args": [
"run", "--rm", "-i", "--pull", "always",
"-e", "COCKTAILPI_BASE_URL=http://cocktailpi/",
"-e", "COCKTAILPI_USERNAME=your-username",
"-e", "COCKTAILPI_PASSWORD=your-password",
"ghcr.io/rizz360/cocktailpi-mcp:latest"
]
}
}
}Use either username/password or a token in the -e values:
- Username/password:
COCKTAILPI_USERNAME+COCKTAILPI_PASSWORD - Token:
COCKTAILPI_ACCESS_TOKEN=your-jwt-token(replace the username/password env vars)
"--pull", "always" makes Docker check for a newer image at each launch.
Core operations:
list_recipes: list recipes/cocktailscreate_recipe: create a new recipeupdate_recipe: update an existing recipeanalyze_pump_ingredient_optimization: strict full-automation and replacement analysis across all recipesanalyze_current_pump_contributions: identify least-contributing current pump ingredients and suggest stronger replacements from barset_ingredient_in_bar: mark one ingredient as present or absent in the bar inventoryset_ingredients_in_bar: bulk mark ingredients as present or absent in the bar inventoryadd_or_update_recipe_image: add or replace a recipe imageadd_or_update_recipe_image_from_url: add/replace recipe image by URLadd_or_update_recipe_image_from_svg: add/replace recipe image from SVG textdelete_recipe_image: remove a recipe imagedelete_recipe: delete a recipelist_pumps: list pumps and configured ingredients
Helper operations:
login: obtain token from CocktailPi backendget_recipe: fetch one recipe by idlist_ingredients: list ingredient ids/nameslist_categories: list category ids/nameslist_glasses: list glass ids/names
Image notes:
create_recipeandupdate_recipenow accept optionalimage_base64(plus optionalimage_filenameandimage_content_type).image_base64can be raw base64 bytes or a data URL (for exampledata:image/png;base64,...).add_or_update_recipe_image_from_urldownloads image content server-side, so AI only sends a short URL argument.add_or_update_recipe_image_from_svgrenders SVG text to PNG server-side, avoiding large base64 arguments.- For
add_or_update_recipe_image,add_or_update_recipe_image_from_url, anddelete_recipe_image,recipe_jsonis optional. - If
recipe_jsonis omitted, the MCP server fetches the existing recipe and reuses current values for update.
Auth behavior notes:
- Every tool's
tokenparameter is optional. - If
tokenis omitted, the MCP server automatically falls back to configuredCOCKTAILPI_ACCESS_TOKENor an automatic credential login (renewed when the token expires). - Call
loginonly if you need to fetch/refresh a token explicitly.
Minimal create_recipe payload pattern:
{
"name": "New Drink",
"ownerId": 1,
"categoryIds": [],
"productionSteps": [
{
"type": "addIngredients",
"stepIngredients": [
{
"ingredientId": 10,
"ingredientType": "<valid-type-from-backend>",
"amount": 50,
"scale": true,
"boostable": false
}
]
}
]
}Payload gotchas:
- Use
categoryIds(notcategories) and include it even if empty. - Keep ingredient entries flat using
ingredientIdandingredientType(not nested ingredient object). ingredientTypevalues are backend-defined; useget_recipeon an existing recipe to copy a valid value.- Include
ownerIdexplicitly when possible; MCP can infer it from JWT claims if omitted. - Non-matching
ownerIdvalues require an admin-like token, otherwise MCP rejects the write. - If backend ignores admin owner override, MCP returns an explicit owner mismatch error.
- Connection errors usually mean
COCKTAILPI_BASE_URLis not reachable from Docker. - Auth errors usually mean wrong credentials/token or missing permissions.
- If you started this with
docker compose up, stop it and use MCP client config that runsdocker runon demand. no matching manifest for linux/arm64/v8means the published tag does not include Apple Silicon yet. Use--platform linux/amd64in docker args as a temporary workaround, then remove it after a multi-arch release is published.failed to connect to the docker API at unix:///.../.docker/run/docker.sockusually means your MCP client tried to start this server before Docker Desktop finished booting.- Start Docker Desktop first, wait until it reports running, then reconnect MCP.
- Verify with
docker versionandls -la ~/.docker/run/docker.sock. - If this keeps happening, use a source-based MCP command (no Docker daemon required). First install dependencies in the same Python interpreter your MCP client will run:
cd /path/to/CocktailPi-MCP
python -m pip install -r requirements.txtThen use an absolute-path launch command (recommended, avoids relative PYTHONPATH issues):
{
"mcpServers": {
"cocktailpi": {
"command": "sh",
"args": [
"-lc",
"cd /path/to/CocktailPi-MCP && PYTHONPATH=/path/to/CocktailPi-MCP/src /path/to/python -m cocktailpi_mcp.main"
],
"env": {
"COCKTAILPI_BASE_URL": "http://cocktailpi/",
"COCKTAILPI_USERNAME": "your-username",
"COCKTAILPI_PASSWORD": "your-password"
}
}
}
}Tips:
- Replace
/path/to/pythonwith the exact interpreter path (for example fromwhich python). - If you still see
ModuleNotFoundError, install again using that exact interpreter:/path/to/python -m pip install -r /path/to/CocktailPi-MCP/requirements.txt.
Most users can skip this section.
The docker-compose.yml file is mainly a convenient place to keep environment values together while testing. For normal MCP usage, your AI client still launches the server process directly.
If you prefer, copy env values from docker-compose.yml into your MCP client args (-e KEY=value).
Detailed endpoint mapping and recipe payload examples are in docs/REFERENCE.md.
Contributor and local source setup instructions are in CONTRIBUTING.md.
This project is licensed under the European Union Public Licence v1.2 (EUPL-1.2). See LICENSE for details.