Gaggimate MCP
jh-dickson/Gaggimate-MCP
Controle sua máquina de café Gaggia com IA via MCP
Ver no GitHubServidor MCP que integra máquinas de café Gaggia ao Claude para monitoramento em tempo real, controle de extração e gerenciamento de receitas. Oferece telemetria de temperatura, pressão, fluxo e integração com balanças inteligentes via Bluetooth.
Instalação
npx convez-ai jh-dickson/Gaggimate-MCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Monitoramento remoto de extrações de espresso em tempo real
- Automação de ciclos de preparo com ajuste de parâmetros PID
- Análise de logs de extração em alta resolução para otimização
- Gerenciamento de perfis e receitas de café via IA
Veredito

Nicho muito específico para entusiastas de café com hardware Gaggia compatível. Implementação técnica sólida com suporte a mock mode para testes, mas utilidade limitada ao ecossistema Gaggia.
README
A tradução para o português deste README ainda está na fila.
Gaggimate-MCP
A vibe-coded MCP server which allows you to connect your gaggia coffee machine to AI for insights and automated brewing. It exposes an API to the AI to allow it to monitor telemetry in real-time, change operational modes, start/stop extractions, adjust brew PIDs, select profiles, and decode high-resolution binary extraction logs.
A GaggiMate device is required for this to work.
Features
- Real-Time Telemetry: Stream temperature (target vs. actual), pump pressure, flow rate, scale weight, and puck resistance.
- Extraction Control: Remotely trigger, monitor, and abort espresso extractions or grinder cycles.
- Recipe/Profile Management: List, load, save, select, and favorite step-based extraction profiles (such as pre-infusion, blooming, and pressure profiling).
- Binary Data Decoding: Automatically fetches and decodes:
index.bin: The binary shot history index.<shot_id>.slog: High-resolution shot logs containing sensor samples taken at 250ms intervals.
- Bluetooth Scale Integration: Connect, scan, and query smart scale weights (Acaia Lunar, Felicita, etc.).
- Mock Simulator Mode: A complete built-in simulated device environment for offline testing and agent evaluation.
Installation & Prerequisites
The GaggiMate MCP server requires Python 3.10+.
1. Fast Execution using uv (Recommended)
uv is an ultra-fast Python package installer and runner. It can execute scripts with inline PEP 723 dependencies directly without manual virtualenv setup:
# Install uv if you haven't already
pip install uv
# Run the server (it automatically handles mcp, websockets, and httpx)
uv run gaggimate_mcp_server.py
2. Standard Installation
If you prefer standard pip packages, install the dependencies manually:
pip install mcp websockets httpx
python gaggimate_mcp_server.py
Configuration
The server is configured using the following environment variables:
| Variable | Description | Default |
|---|---|---|
GAGGIMATE_HOST | The IP address or mDNS hostname of your Gaggia Classic Pro. Set to mock, localhost, or 127.0.0.1 to enable the built-in simulator. | gaggimate.local |
Claude Configuration
To connect Claude (either Claude Code CLI or the Claude Desktop App) to this MCP server, add the configuration block to your settings file.
Configuration Structure
{
"mcpServers": {
"gaggimate": {
"command": "uv",
"args": [
"run",
"--script",
"/path/to/gaggimate_mcp_server.py"
],
"env": {
"GAGGIMATE_HOST": "gaggimate.local"
}
}
}
}
Configuration Files & Paths
Save the configuration block above in the appropriate path below depending on your environment:
- Claude Code (Project Scope):
Save as
.mcp.jsonin the root of your project directory. In this scope, you can use a relative script path:"/path/to/gaggimate_mcp_server.py"➔"gaggimate_mcp_server.py" - Claude Code (Global Scope):
Save in your home directory as
~/.claude.json. Ensure you use the absolute path togaggimate_mcp_server.py. - Claude Desktop App:
Add to your desktop settings file (ensure you use the absolute path to the script):
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
[!TIP] Running without
uv: If you do not haveuvinstalled, change the"command"to"python"(or"python3") and remove"run"and"--script"from the"args"list, leaving only the script path.
Offline Mock Simulator Mode
To test your AI agent's capabilities offline or during development, enable the mock device simulation by setting the host environment variable to mock:
# Set environment variable and launch
set GAGGIMATE_HOST=mock
uv run gaggimate_mcp_server.py
The simulator mimics:
- Temperature fluctuations and heating curves for brewing and steaming.
- Brew and grinder processes (including target volumetric coffee weight check).
- Profile saving, loading, selecting, and indexing.
- Dynamically packing/compiling binary shot logs (.slog) and history files (.bin) to test the decoder functions.
Tool Reference
The server exposes 21 tools categorized below:
Telemetry & Machine State
get_device_status()- Retrieves real-time variables: temperatures, active modes, pump flow, puck resistance, scale weight connection, active process details, and water levels.
change_mode(mode: str)- Changes operational state. Choose from:
'standby','brew','steam','water', or'grind'.
- Changes operational state. Choose from:
adjust_temperature(action: str)- Increments or decrements target boiler temperatures. Action must be
'raise'or'lower'.
- Increments or decrements target boiler temperatures. Action must be
start_flush()- Clean the grouphead by executing a backflush pulse cycle.
Extraction & Grinder Control
control_brew(action: str)- Triggers, cancels, or resets an extraction. Action must be
'activate','deactivate', or'clear'.
- Triggers, cancels, or resets an extraction. Action must be
control_grind(action: str)- Toggles the smart grinder attachment. Action must be
'activate'or'deactivate'.
- Toggles the smart grinder attachment. Action must be
adjust_target(grind: bool, mode: str, target: int)- Sets coffee dosage cutoff criteria: by weight (volumetric) or by duration (time-based).
Profile & Recipe Sheets
list_profiles(minimal: bool)- Lists profiles stored in SPIFFS filesystem.
load_profile(profile_id: str)- Fetches step configurations (phases, pressure curves, targets) for a profile.
save_profile(profile: dict)- Creates or edits profile recipes on the device.
delete_profile(profile_id: str)- Removes a profile file from memory.
select_profile(profile_id: str)- Configures the machine to use this profile during the next extraction.
favorite_profile(profile_id: str, favorite: bool)- Star or unstar a specific recipe profile.
Shot History & Log Decoder
list_history()- Fetches
index.bin, decodes the binary index entries structure, filters out deleted logs, and returns a clean, chronological JSON list of shot history.
- Fetches
get_shot_log(shot_id: str)- Downloads the high-resolution binary
<shot_id>.slogfile, decodes the sensor payload (temperature, pressure, puck resistance, water flow, scale weight sampled every 250ms), and returns structured timeseries datasets along with phase transition milestones.
- Downloads the high-resolution binary
delete_shot_log(shot_id: str)- Permanently deletes a history record.
get_shot_notes(shot_id: str)- Gets stars rating (1-5), dose inputs, dose outputs, and comments.
save_shot_notes(shot_id: str, notes: dict)- Saves review notes, rating, and weight calibrations.
Bluetooth Scale & Hardware Settings
manage_scale(action: str, uuid: str)- Connects, scans, lists, or queries smart scale Bluetooth devices.
get_settings()- Fetches device configuration variables (timezone, brightness, auto-wakeup, Wi-Fi parameters).
update_settings(settings: dict)- Modifies controller system configuration.