Gaggimate MCP
About
Allows an LLM agent to control your Gaggimate espresso machine
Details
- Author
- julianleopold
- Categories
- Other, AI
Jump to
1. Install uv (if not already installed)
](https://docs.astral.sh/uv/)uvis a fast Python package manager. Install it with:
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Or with Homebrew brew install uv
git clone https://github.com/julianleopold/gaggimate-mcp.git cd gaggimate-mcp uv sync
Find youruvpath (you'll need the full absolute path):
which uv # Example output: /opt/homebrew/bin/uv
pwd # Example output: /Users/yourname/code/gaggimate-mcp
Open Claude Desktop settings:Settings → Developer → Edit Config
Add this configuration (replace paths with your actual values):
{ "mcpServers": { "gaggimate": { "command": "/opt/homebrew/bin/uv", "args": [ "--directory", "/Users/yourname/code/gaggimate-mcp", "run", "mcp", "run", "src/gaggimate_mcp/server.py" ] } } }
For other MCP hosts, configure the server using the stdio transport with the command:
uv --directory /path/to/gaggimate-mcp run mcp run src/gaggimate_mcp/server.py
DIY AI Barista— Let your AI agent directly control your Gaggimate
Blog Post:I Turned Claude Into an AI Barista Controlling My Espresso Machine
You can already ask an LLM for advice on how to dial your espresso, and models like Claude, ChatGPT, or Gemini can already generate Gaggimate profiles in JSON format.
-
An MCP serverthat allows your LLM agent to directly interact with your Gaggimate machine—no copy-pasting or manually uploading required. Your LLM agent can read your shot history, analyze extractions, store your tasting feedback, upload generated profiles, and adjust them based on your results and wishes.
Instructions, knowledge, and skillsto guide the agent on how to help you dial your espresso—turning a general-purpose LLM into a barista coach that understands extraction theory, tasting vocabulary, pressure profiling, and Gaggimate's profile system. Thanks to Charlie Hall for allowing me to use and adapt the knowledge files and diagnostic patterns from hisgaggimate-baristaproject.
- What's in this Repository
- Changelog
- The Dialing Flow
- Example Conversations
- MCP Tools
- MCP Resources
- Safety Guardrails
- Requirements
- Quick Start
- Claude Desktop Project Setup (Optional)
- Configuration (Optional)
- Troubleshooting
- How It Works
- Local Data Storage
- Development
- Why a Skill Instead of a Knowledge File?
- Project Structure
- Related
- License
MCP Server— Nine tools and eight resources that give your AI direct access to your machine and local data:
- Read shot data— Temperature curves, pressure readings, flow rates, extraction timing
- Manage profiles— Create, update, and list brewing profiles directly on your device
- Track feedback— Record ratings and tasting notes synced to your Gaggimate
- Browse history— List recent shots with filtering
- Diagnose issues— Automated connection troubleshooting
- Manage coffees— Create and update coffee tracking files with brewing journal
- User setup— Store and retrieve your equipment and preferences
- Grind map— Track successful grind settings across coffees
- Brewing insights— Accumulate cross-coffee patterns and learnings
- Knowledge resources— On-demand access to espresso knowledge files (including subdirectories)
Knowledge Files(10 files) — Reference materials that transform a general-purpose LLM into a functional barista coach:
- Espresso extraction theory, shot styles, and variable hierarchy
- Tasting vocabulary (how to describe sour vs bitter, body, sweetness)
- Pressure guide with roast × processing matrix
- Extraction science (channeling, puck prep, pre-infusion mechanics)
- Bean freshness and storage (CO2 timeline, rest windows)
- Profile library with 8 ready-to-use templates
- Basket sizing and dose rules
- Milk steaming and drink specs
- Decaf and blend strategies
- Complete Gaggimate profile schema and examples
Skills(5 skills) — Claude Desktop skills using progressive disclosure (load detailed references only when needed):
- gaggimate-profiles— Profile creation with conditional reference loading
- new-coffee— Research new beans, recommend parameters, upload profile
- diagnose— Shot telemetry analysis with taste-data correlation
- feedback— Full shot feedback loop with recording and recommendations
- knowledge-lookup— Knowledge Q&A router that cites the correct knowledge file
- Channeling indicators v2: Rewrote the channeling-risk computation around four independent indicators, each catching a specific physical signature, with descriptor fields separated from scored indicators.
- Window trim (V4): After the existing pressure-ramp trim, also strips leading & trailing zero-flow samples (valve-closed at entry, volumetric-cutoff at exit). Eliminates the class of false-positive HIGH ratings caused by trapped-pressure tails.
- Flow jitter (V5):flow_jitter_ml_sreplaces raw std as the primary flow-instability indicator. Measures first-difference std, so designed flow ramps no longer inflate the score. New annotation bands: STABLE <0.05, MODERATE_JITTER 0.10–<0.20, JITTERY ≥0.20; the scored threshold for +2 points begins at ≥0.10.
- Target tracking (V6):flow_vs_target_residual_ml_s— std of (actual − target) flow — is the clearest channeling fingerprint on flow-led profiles.nullon pressure-led profiles, in which casepressure_jitter_barfills the indicator slot.
- Late-flow runaway detrended:flow_acceleration_late_ml_s2is nowlate_slope − overall_slopeso that ramping-flow profiles read as stable rather than "accelerating at end."
- Field renames (breaking):ChannelingIndicators.overall_risk→channeling_risk;flow_volatility_ml_s→flow_spread_ml_s(descriptor, unscored);pressure_volatility_bardropped in favor ofpressure_jitter_bar. Per-phasepressure_stability_bar/flow_stability_ml_srenamed topressure_jitter_bar/flow_jitter_ml_sto match.
- Agent-facing annotations: Newprimary_signal,guidance,flow_shape,window_confidenceannotations make it clear to the LLMwhya rating fired and how much confidence to give it.
- Diagnose skill version bumped;SHOT_DIAGNOSTICS_REFERENCE.mdrewritten for the new schema.
- Knowledge deduplication Phase 3: SlimmedGAGGIMATE_PROFILE_CREATION_GUIDE.mdfrom 1113 → 130 lines (88% reduction). Now a navigation hub that links to detailedknowledge/profiles/sub-files instead of duplicating their content
- Coffee processing reference: AddedCOFFEE_PROCESSING.md— comprehensive guide to 7 processing methods (washed, natural, honey, etc.) and their espresso extraction implications
- Cross-references enriched: Added processing method links toPRESSURE_GUIDE.mdandINSTRUCTIONS.md
- Agent-facing words: Reduced from 29,828 → 27,869 (~1,960 word reduction) through deduplication while filling content gaps
- Physics-informed shot diagnostics:analyze_shotnow computes puck resistance (P/F²), channeling risk scoring, temperature deviation tracking, pressure/flow stability, profile compliance metrics, and per-phase breakdowns — all with human-readable band annotations
- 3-level detail system: Newdetailparameter (summary/per_phase/detailed) controls diagnostic depth vs. token cost. Summary for triage, per_phase for isolating problems, detailed for full time-series
- Calibrated diagnostic thresholds: Pressure drop rate bands widened for 100ms sample noise, temperature overshoot bands tightened to match INEI ±2°C tolerance, ramp rate labels renamed from SLOW/FAST to GENTLE/AGGRESSIVE to avoid value judgments on intentionally slow preinfusion ramps
- Research documentation: Addedknowledge/research/ESPRESSO_PHYSICS_AND_THRESHOLD_CALIBRATION.mdwith physics rationale and source citations for all threshold decisions
- Narrative coffee tracking: Coffee files now store analysis and insights instead of raw numbers — brewing approach (narrative), journal entries (dated analysis), and key insights. Raw shot data stays on the device; the agent recordsthinkingandlearnings
- Brewing insights: Newmanage_brewing_insightstool andgaggimate://user/brewing-insightsresource for cross-coffee pattern recognition — what works for which origin, which profiles suit which processing method, general learnings that carry across coffees
- Knowledge as MCP resources: Moved 10 skill reference files (profile structure, pump modes, diagnostic trees, telemetry patterns, etc.) from bundled skill directories intoknowledge/{profiles,diagnostics,research}/subdirectories, served via MCP resources. Skills are now lightweight single-file SKILL.md that load references on-demand viagaggimate://knowledge/{subdir}/{filename}
- Skill integration improvements: Knowledge-lookup skill now routes to user data resources (grind map, setup, coffees). Diagnose skill reads coffee history for context. Feedback skill cross-references grind map for successful settings
- Renamed consult → knowledge-lookup: Skill name now describes what it does — looks up espresso knowledge from authoritative files
- Simplified manage_coffee tool: Reduced from 27 to 16 parameters. Replacedlog_shotaction (8 numeric columns) withlog_entryaction (date, headline, narrative body)
- Test coverage: 206 tests passing (up from 192)
- MCP Resources: Added 6 read-only MCP resources for on-demand access to knowledge files, coffee tracking files, user setup, and grind map — no more manual file uploads needed
- Coffee tracking tool: Newmanage_coffeeMCP tool to create, update, delete coffee files and log shots with persistent tracking across sessions
- User setup tool: Newmanage_user_setupMCP tool to store and retrieve equipment/preferences
- Grind map tool: Newmanage_grind_mapMCP tool to track successful grind settings across coffees
- Directory restructure:agent-knowledge/→knowledge/, newcoffees/anduser/directories for local data
- Updated instructions & skills: All agent instructions and skills now reference MCP resources and tools instead of static file uploads
- Storage helpers: Newstorage/markdown.pymodule for markdown file CRUD operations
- Partial profile updates: Update only the fields you want to change (temperature, phases, or name) - omitted fields keep their existing values
- Delete profiles: Addedaction='delete'tomanage_profilewith safety guardrails:
- Only AI-created profiles (ending with[AI]) can be deleted
- Requires explicitconfirm_delete=Trueto prevent accidents
- Deleted profiles can be recovered from local backup (seeLocal Data Storage)
- Configurable AI markers(edc8d98): AI profile suffix and notes prefix are now configurable viaGAGGIMATE_AI_PROFILE_SUFFIXandGAGGIMATE_AI_NOTES_PREFIXenvironment variables
- Bug fix(a350246): Profile updates now preserve valve settings and profile type (simple/pro) instead of resetting them
- Automatic Pro documentation(bfc2ca0): Added comprehensive guide for Automatic Pro profiles with flow-based variable pressure examples
flowchart LR A[☕ Pull shot] --> B[💬 AI asks for feedback] B --> C[📝 Stored in shot notes] C --> D[🤖 AI analyzes & suggests] D --> E[📋 AI updates profile] E --> A
Iteratively improve your shots with AI-guided feedback:
- Pull a shotand taste it
- AI prompts you for feedback—it'll ask targeted questions about balance (sour/bitter), body, sweetness, and specific flavors to help you articulate what you're tasting
- Feedback is savedto your shot notes on Gaggimate, creating a record of your dialing journey
- AI analyzesyour shot data (pressure curves, temperature, flow) combined with your tasting notes
- AI suggests adjustments—explainingwhy(e.g., "that sourness suggests under-extraction, let's grind finer or increase temperature")
- AI updates your profiledirectly on your machine, or recommends grind changes
- Repeatuntil dialed in
- Share a photo of your coffee bag, or just tell the AI what you're brewing
- The AI willresearch your beansusing web search—finding roaster info, processing method, altitude, variety, and tasting notes
- Based on that research plus your equipment and preferences, it creates an optimized starting profile
- On first use, it'll ask about your setup (machine, grinder, basket size) to give better recommendations
"Here is a picture of this coffee I got. Can you please research it and create a Gaggimate profile for it?"
"I just pulled a shot—ask me about it"
AI will prompt: "How would you rate it 1-5? Was it sour, balanced, or bitter? Anything else you noticed—sweetness, body, specific flavors?"
"Can you please update the feedback for my most recent shot. It tasted a bit bitter. Give it a 2/5 rating. I used grind setting 12 with 15g in and 30g out."
"Please look at all my recent shots with the Amizade coffee beans. Based on my feedback in each shot, how should we adjust the profile?"
You:I have some light roast Ethiopian beans. Can you create a profile?
AI:I'll create a profile optimized for light roast Ethiopian beans. Light roasts typically benefit from higher temperatures and longer pre-infusion...
Creates "Ethiopian Light [AI]" profile with appropriate settings
You:Analyze my last shot, it tasted sour
AI:Looking at shot #127... The extraction was 24 seconds with an average pressure of 8.2 bar. The flow rate increased rapidly after pre-infusion, which combined with the sour taste suggests under-extraction. I'd recommend:
- Grinding finer
- Increasing temperature by 1-2°C
- Extending pre-infusion time
You:Rate that last shot 4 stars - much better, slight bitterness remaining
AI:I've saved your rating and notes. Looking at your progression, your last 3 shots have improved from 2 to 4 stars. The bitterness might indicate we're now slightly over-extracting. Want me to adjust the profile?
This server provides eight tools and six resources that give AI agents the capabilities they need to help with your espresso workflow:
Create, view, update, delete, and list brewing profiles on your Gaggimate device. Profiles define the entire extraction process—water temperature, pre-infusion settings, pressure curves, and flow targets. The AI can build profiles optimized for specific beans or brewing styles.Partial updatesare supported—you can change just temperature, phases, or name without respecifying everything. Profiles created by AI are automatically tagged with[AI]in their name so you can identify them.
Retrieve and analyze any shot with a3-level detail systemthat balances insight vs. token cost:
- summary(default): Key indicators for quick triage — puck resistance, channeling risk, temperature stability, profile compliance, and human-readable annotation labels. Start here.
- per_phase: Full diagnostics plus per-phase breakdowns (preinfusion ramp rate, brew stability, decline taper smoothness) with representative samples. Use when diagnosing which phase has a problem.
- detailed: Everything inper_phaseplus all time-series samples. Use for deep analysis when exact timings matter.
Raw binary shot logs are parsed and transformed into an AI-friendly format with physics-informed diagnostics: puck resistance modeling (P/F²), channeling risk scoring, temperature deviation tracking, pressure/flow stability analysis, and profile compliance metrics. Every numeric metric is accompanied by a band annotation (e.g.,MODERATE,STABLE,SLIGHT_OVERSHOOT) so the AI can interpret values without needing to know the thresholds.
Record ratings (0-5 stars), tasting notes, and brewing parameters for any shot. Notes are synced directly to your Gaggimate device via WebSocket and also stored locally as backup. You can track taste balance (bitter/balanced/sour), grind settings, and dose weights. Notes added by AI are prefixed with[AI]:for transparency.
Browse your shot history with optional filtering. Returns a list of recent shots with their IDs, timestamps, profile names, and any ratings you've recorded. This helps the AI understand your brewing patterns and find shots to analyze or compare.
Troubleshoot connectivity issues between the MCP server and your Gaggimate device. Runs automated tests for network reachability, HTTP port access, API availability, and common misconfigurations. Returns specific recommendations if problems are detected.
Create and manage coffee tracking files. Each coffee gets a markdown file with bean profile, brewing approach (narrative), and a brewing journal with dated analysis entries. The agent records what worked, what didn't, and what to try next — not raw numbers. Supports creating new coffees, logging journal entries, updating content, deleting files, and listing all tracked coffees.
Store and retrieve your equipment setup and preferences — machine, grinder, basket, scale, drink preferences, puck prep routine. Saved locally and accessible across all sessions.
Track successful grind settings across different coffees. When you find a setting that works (4-5 star shots), record it here for future reference when you revisit a coffee or try something similar.
Accumulate cross-coffee patterns and learnings. When the agent notices patterns (e.g., "Brazilian naturals do well with declining profiles"), it records them here. The new-coffee skill reviews this file first when dialing in unfamiliar beans, leveraging past experience.
The server also exposes eight resources that provide on-demand access to local files:
For safe operation, this MCP server enforces the following limits:
- No shot control: The AI cannot start, stop, or trigger espresso shots. It can only read shot data and manage profiles.
- Temperature limits: All temperatures are clamped to25-100°Cto prevent damage or burns.
- Pressure limits: All pressures are clamped to0-12 barto stay within safe operating ranges.
- Profile attribution: AI-created profiles are marked with[AI]suffix (e.g., "Ethiopian Light [AI]") for transparency.
- Delete protection: The AI can only delete profiles it created (those ending with[AI]). User-created profiles cannot be deleted by the agent. If you need to recover a deleted profile, seeLocal Data Storage—all profile versions are saved locally before deletion.
These limits are enforced at the configuration level and cannot be overridden through the MCP tools.
- AGaggimate-modded espresso machine (Gaggia Classic, etc.)
- An MCP host application (e.g.,Claude Desktop,VS Code with GitHub Copilot, or any other MCP-compatible client)
- Python 3.11+ withuvpackage manager
- Same network access as your Gaggimate device
1. Install uv (if not already installed)
uvis a fast Python package manager. Install it with:
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Or with Homebrew brew install uv
git clone https://github.com/julianleopold/gaggimate-mcp.git cd gaggimate-mcp uv sync
Find youruvpath (you'll need the full absolute path):
which uv # Example output: /opt/homebrew/bin/uv
pwd # Example output: /Users/yourname/code/gaggimate-mcp
Open Claude Desktop settings:Settings → Developer → Edit Config
Add this configuration (replace paths with your actual values):
{ "mcpServers": { "gaggimate": { "command": "/opt/homebrew/bin/uv", "args": [ "--directory", "/Users/yourname/code/gaggimate-mcp", "run", "mcp", "run", "src/gaggimate_mcp/server.py" ] } } }
For other MCP hosts, configure the server using the stdio transport with the command:
uv --directory /path/to/gaggimate-mcp run mcp run src/gaggimate_mcp/server.py
4. Restart Your AI Chat Application / MCP Host
Restart your AI chat application (e.g., Claude Desktop, VS Code) to load the new server configuration. You should see the Gaggimate tools become available.
Make sure you're on the same network as your Gaggimate device, then try:
- "List my Gaggimate profiles"
- "Show my recent espresso shots"
- "Diagnose my Gaggimate connection" (if having issues)
This repository includes pre-built files for setting up aClaude Desktop Projectdedicated to espresso dialing. Projects combine system instructions, knowledge files, and MCP tools into a focused workspace.
Using a different AI?You can copy-paste the knowledge files into any chat, or adapt the instructions for your preferred agent.
agent-instructions/ └── INSTRUCTIONS.md # System primer for the espresso dialing agent knowledge/ ├── ESPRESSO_BREWING_BASICS.md # Extraction fundamentals, variable hierarchy, diagnostic tree ├── ESPRESSO_TASTING_GUIDE.md # Shot evaluation, sour vs bitter, tasting methodology ├── GAGGIMATE_PROFILE_CREATION_GUIDE.md # Complete JSON schema for Gaggimate profiles ├── PRESSURE_GUIDE.md # Pressure by roast × processing method ├── EXTRACTION_SCIENCE.md # Channeling, puck prep, pre-infusion mechanics ├── BEAN_FRESHNESS_AND_STORAGE.md # CO2 timeline, rest windows, storage ├── PROFILE_LIBRARY.md # 8 ready-to-use profile templates ├── BASKETS.md # Dose rules, basket sizing ├── MILK_AND_DRINKS.md # Steaming, drink specs, single-boiler workflow ├── SPECIAL_CATEGORIES.md # Decaf adjustments, blend strategies ├── profiles/ # Profile creation references (structure, pumps, examples) ├── diagnostics/ # Diagnostic trees, telemetry patterns, shot diagnostics reference └── research/ # Research checklists, espresso physics & threshold calibration agent-skills/ ├── gaggimate-profiles/ # Profile creation with conditional reference loading ├── new-coffee/ # Research beans → recommend parameters → upload profile ├── diagnose/ # Shot telemetry analysis with taste correlation ├── feedback/ # Shot feedback loop: gather → analyze → record → recommend └── knowledge-lookup/ # Knowledge Q&A router (cites correct knowledge file) coffees/ # Coffee tracking files (created by AI, gitignored) user/ # User setup and grind map (created by AI, gitignored) ├── user-setup.example.md # Template for user equipment/preferences └── grind-map.example.md # Template for grind settings tracking
- Create a new projectin Claude Desktop
- Add the system instructions: Copy the contents ofagent-instructions/INSTRUCTIONS.mdinto the project's system prompt
- Connect the MCP server: Follow theQuick Startabove — knowledge files are served automatically via MCP resources
- Optional - Upload knowledge files: If your MCP client doesn't support resources, add files fromknowledge/to the project's knowledge section
- Optional - Install skills: SeeAppendix: Why a Skill?for details
By default, the server connects togaggimate.local, which should work automatically if your Gaggimate device is on the same network.Most users can skip this section.
If you need to customize the connection, create a.envfile:
GAGGIMATE_HOST=gaggimate.local # Device hostname or IP GAGGIMATE_PROTOCOL=ws # Protocol (ws or http) GAGGIMATE_LOG_LEVEL=INFO # Logging level
If your device doesn't resolve via mDNS, use the IP address directly:
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
