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 |

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