convez.ai
MCP ServerAutomaçãoAvançado
jh-dickson

Gaggimate MCP

jh-dickson/Gaggimate-MCP

Controle sua máquina de café Gaggia com IA via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-MCP

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

VariableDescriptionDefault
GAGGIMATE_HOSTThe 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:

  1. Claude Code (Project Scope): Save as .mcp.json in 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"
  2. Claude Code (Global Scope): Save in your home directory as ~/.claude.json. Ensure you use the absolute path to gaggimate_mcp_server.py.
  3. 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

[!TIP] Running without uv: If you do not have uv installed, 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'.
  • adjust_temperature(action: str)
    • Increments or decrements target boiler temperatures. Action must be 'raise' or 'lower'.
  • 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'.
  • control_grind(action: str)
    • Toggles the smart grinder attachment. Action must be 'activate' or 'deactivate'.
  • 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.
  • get_shot_log(shot_id: str)
    • Downloads the high-resolution binary <shot_id>.slog file, 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.
  • 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.
Ver o original no GitHub

Bom para

Relacionados