Gaggiuino MCP server

Gaggiuino MCP Server

A Remote MCP server for integrating a Gaggiuino espresso machine with AI tools. Ask your AI assistant to check machine status, analyze shot data, and get dial-in guidance.

Features

MCP Tools

Shot Analysis

• get_status - Current machine status (temperature, pressure, weight, water level)
• getlatestshot_id - Most recent shot, id and headline numbers in one call
• listrecentshots - The last few shots summarised, for trends over a session
• getshotdata - Structured shot summary with metrics
• getshotraw_data - Complete time-series data
• viewshotgraph - Interactive shot graph rendered in MCP-compatible hosts (pressure, flow, weight over time with target overlays and optional shot comparison)

Profiles and Settings

• list_profiles - Profiles on the machine, merged with this server's documentation
• getprofileinfo - Everything known about one profile
• getmachinesettings - Boiler, steam, and scale configuration as the machine reports it
• getmaintenancestatus - Descale and backflush history the machine tracks itself, with shots since each
• getdialin_guidance - Expert guidance for analyzing espresso shots
• select_profile - Switch the active profile (changes the machine; requires an authenticated server)
• upload_profile - Save a new brew profile to the machine (changes the machine; requires an authenticated server). Creates only — it never updates, and the machine assigns a fresh id every time, so uploading twice leaves two profiles
• delete_profile - Delete a profile from the machine (destructive and irreversible; requires an authenticated server). It demands the profile's exact name back as confirmation, refuses to delete the currently selected profile, and always prompts for approval in the host — even under a stored "always allow"

MCP Prompts - workflow templates your host surfaces as slash commands or menu items:

• dialinnew_bag - first shots on a coffee you have not pulled before (bean, and optionally roast level, dose, and what you want in the cup)
• diagnoselastshot - read the shot you just pulled against how it tasted (what was wrong, and optionally what you changed)
• choose_profile - pick a profile the machine actually holds for a coffee (roast level, and optionally drink and notes)
• espressoshotanalyst - the dial-in guidance as a system prompt (same content as getdialin_guidance)

Each workflow prompt lays out the tools to call in order, so the analysis starts from the machine's own data rather than a guess.

MCP Resources - gaggiuino://profiles and gaggiuino://profiles/{id} for profile data

Quick Start

The server is published as a multi-arch image (linux/amd64, linux/arm64) at ghcr.io/ljcl/gaggiuino-mcp, so there is nothing to clone or build. It is also listed in the MCP Registry as io.github.ljcl/gaggiuino-mcp.

1. Download and Configure

mkdir gaggiuino-mcp && cd gaggiuino-mcp

curl -O https://raw.githubusercontent.com/ljcl/gaggiuino-mcp/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/ljcl/gaggiuino-mcp/main/.env.example

Edit .env with your Gaggiuino machine's address:

# Use the IP directly (recommended)
GAGGIUINO_URL=http://192.168.1.100

# Or if mDNS works on your network
GAGGIUINO_URL=http://gaggiuino.local

2. Start the Server

docker compose up -d

3. Verify

curl http://localhost:8000/health

The server is available at http://:8000/mcp.

Choosing a Version

The compose file tracks latest. To pin a release, set GAGGIUINOMCPTAG in .env:

GAGGIUINO_MCP_TAG=3.2    # latest 3.2.x patch
GAGGIUINO_MCP_TAG=3.2.0  # exact release

Shortened. The full README is on GitHub.