Skip to main content
Glama
grr-gaggiuino-mcp

grr-gaggiuino-mcp

by sgerlach

grr-gaggiuino-mcp

An MCP (Model Context Protocol) server for Gaggiuino-modified espresso machines.

Monitor your machine, analyze shots, and manage brewing profiles from any MCP-compatible client.

Tools

Tool

Description

get_status

Real-time machine state: temperature, pressure, weight, water level, active profile, brewing/steaming status

get_shot

Shot data with time-series curves (pressure, flow, temp, weight) and profile used. Defaults to latest shot.

get_profiles

List all brewing profiles with IDs and selection status

select_profile

Activate a brewing profile by ID

Related MCP server: meticulous-mcp

Installation

Prerequisites

  • Node.js 18+

  • A Gaggiuino-modified espresso machine on your local network

Option 1: npx (easiest)

No install needed - just configure Claude Desktop to use npx:

{
  "mcpServers": {
    "gaggiuino": {
      "command": "npx",
      "args": ["grr-gaggiuino-mcp"],
      "env": {
        "GAGGIUINO_BASE_URL": "http://YOUR_GAGGIUINO_IP"
      }
    }
  }
}

Option 2: Clone and Build

git clone https://github.com/sgerlach/grr-gaggiuino-mcp.git
cd grr-gaggiuino-mcp
npm install
npm run build

Claude Desktop Configuration

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gaggiuino": {
      "command": "node",
      "args": ["/path/to/grr-gaggiuino-mcp/dist/index.js"],
      "env": {
        "GAGGIUINO_BASE_URL": "http://YOUR_GAGGIUINO_IP"
      }
    }
  }
}

Note: If using nvm, specify the full path to Node 18+:

"command": "/Users/you/.nvm/versions/node/v20.x.x/bin/node"

Configuration

Variable

Default

Description

GAGGIUINO_BASE_URL

http://192.168.3.248

Your Gaggiuino's IP or hostname

REQUEST_TIMEOUT

5000

API timeout in milliseconds

Testing

# With MCP Inspector
npm run inspect

# Direct run
GAGGIUINO_BASE_URL=http://YOUR_IP npm start

Example Workflows

Quick Status Check

You: "Is my machine ready to pull a shot?"
→ get_status: temp 93°C (target 93°C), pressure stable, water level 85%

Dialing In a New Coffee

You: "I have a new bag of coffee - Ethiopian Yirgacheffe, light roast,
      tasting notes of blueberry and citrus. It's 10 days off roast.
      What profile should I start with?"

→ LLM recommends a profile based on the coffee characteristics

You: "OK I pulled the shot, analyze it"
→ get_shot returns pressure/flow/temp curves

You: "It tasted sour and watery"
→ LLM analyzes the shot data against your taste feedback:
   "The pressure ramped too quickly and flow was high (4.2 ml/s).
    Try grinding 2 steps finer. The 6:1 ratio in 24s suggests
    under-extraction - aim for 28-32s."

You: "Pulled another shot after adjusting"
→ get_shot for the new shot
→ "Much better - pressure curve is smoother, 2.8 ml/s flow.
    How did it taste?"

Shot Analysis & Troubleshooting

You: "My shots have been channeling lately, look at my last few shots"
→ get_shot (latest), get_shot (id: previous)
→ LLM identifies pressure spikes/instability indicating channeling

You: "Compare this shot to yesterday's good one"
→ Side-by-side analysis of shot curves

Profile Management

You: "What profiles do I have?"
→ get_profiles lists all available profiles

You: "Switch to my low-pressure blooming profile"
→ select_profile activates it

You: "Pull a shot and tell me if this profile works for my current beans"
→ get_shot + analysis based on bean characteristics you've shared

Iterative Dial-In Session

You: "Let's dial in this coffee. Medium-dark Brazilian, chocolate/nutty,
      for milk drinks. 18g dose, targeting 36g out."

→ LLM suggests starting parameters and profile

[Pull shot 1]
You: "Done, check it"
→ get_shot → "23 seconds, slightly fast. Bitter finish suggests
   over-extraction at the end despite short time - likely channeling.
   Grind 1 step finer and improve puck prep."

[Pull shot 2]
You: "Better prep this time"
→ get_shot → "27 seconds, smooth pressure curve. How's the taste?"

You: "Really good! Balanced, nice chocolate, good body for a cortado"
→ "Great - this is your baseline. Shot data saved.
    Current recipe: 18g → 36g in 27s, Profile: X"

Unit Conversions

The Gaggiuino API returns values in deci-units. This server converts them to standard units:

Raw API

Converted

deciseconds

seconds

decibar

bar

decidegrees

°C

decigrams

grams

deci-ml/s

ml/s

API Reference

Based on the Gaggiuino REST API.

License

MIT

Available Tools

4 tools
get_profilesA

List all available brewing profiles stored on the Gaggiuino. Returns profile IDs, names, and which one is currently selected. Use this to see available profiles before selecting one.

Inputs: no named parameters.

get_shotA

Retrieve detailed shot data with time-series curves for analysis. Returns pressure (bar), flow rate (ml/s), temperature (C), weight (g), and target values over time. Includes the profile used and shot duration. Omit ID to get the most recent shot.

Inputs: id.

get_statusA

Get real-time Gaggiuino espresso machine status including: current/target temperature (Celsius), pressure (bar), scale weight (grams), water tank level (%), whether brewing or steaming is active, and the currently selected profile name and ID.

Inputs: no named parameters.

select_profileA

Activate a brewing profile by its ID. The machine will use this profile for the next shot. Get available profile IDs using get_profiles first.

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: live status, historical shot data, profile listing, and profile selection. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: get_status, get_shot, get_profiles, select_profile. The naming is uniform and predictable.

    Tool Count5/5

    Four tools is well-scoped for a focused Gaggiuino interface. Each tool serves a clear need without redundancy or bloat.

    Completeness4/5

    The set covers core workflows: monitoring status, retrieving shot data, browsing profiles, and selecting one. Missing profile editing and brew control are minor gaps that do not break the main use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers