Meticulous Espresso MCP Server

Your Meticulous espresso machine, connected to an LLM. Generate recipes from natural language, analyze shots, dial in your grinder, and keep a persistent shot diary — all through Claude.

No Anthropic API key required. No cloud subscription. Just your machine, your LLM, and a local IP.

---

Get started in 60 seconds

Add this to your Claude Desktop or Claude Code config and you're done:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Code — ~/.claude.json

{
  "mcpServers": {
    "meticulous": {
      "command": "npx",
      "args": ["-y", "github:erdos2n/meticulous-mcp-server"],
      "env": {
        "METICULOUS_IP": "192.168.x.x"
      }
    }
  }
}

Replace 192.168.x.x with your machine's local IP (find it in your router or the Meticulous app). Restart Claude. That's it — no cloning, no building, no dependencies to manage.

Want this on Claude mobile or claude.ai? You'll need a Raspberry Pi on your local network. See LLM_SETUP.md and PI_SETUP_INSTRUCTIONS.md.

---

What you can do

Pull the shot data from my last espresso and tell me what to adjust.

Generate a recipe for a washed Ethiopian, 18g dose, 1:2.5 ratio, slow bloom.

Save my grinder setting — I'm on the DF83 at 10.2 for the Osmotic flow profile.

Read my shot diary and tell me what's been working.

My last three shots were sour. Look at the shot data and suggest a fix.

List all my profiles and load the one I used last week for the natural.

---

What it does

• Generate and tweak recipes from plain language, validated and loaded to the machine
• Analyze shots — pulls sensor data and gives concrete recipe improvement suggestions
• Manage profiles — list, load, save, delete, browse factory and community recipes
• Control the machine — start, stop, tare, preheat, reset
• Track grinder settings per profile across sessions — never re-explain your dial-in
• Keep a shot diary — tasting notes and observations that persist between chats

The grinder settings and diary are stored as plain files in ~/.meticulous-mcp/ on your machine. No database, no setup — just open them in any text editor.

---

All available tools

Machine control

Tool	What it does
get_device_info	Firmware, serial, model, software version
execute_action	start / stop / tare / preheat / reset / calibration
get_settings	Read machine settings
update_setting	Change machine settings
get_notifications	Pending or acknowledged machine notifications

Profiles

Tool	What it does
list_profiles	All profiles stored on the machine
get_all_profiles	Full details for every profile
get_profile	Single profile by UUID
get_last_profile	Currently active profile
get_default_profiles	Factory + community profiles
load_profile	Load a recipe (temporary)
load_profile_by_id	Load an existing profile by UUID
save_profile	Save a recipe to the machine permanently
delete_profile	Remove a profile by UUID
validate_recipe	Check schema + auto-fix simple errors

Shot history

Tool	What it does
get_shot_history	Recent shots with metadata
search_history	Filter by name, date, order, limit
get_current_shot	Real-time data for a shot in progress
get_last_shot	Sensor data for the most recent shot
get_shot_statistics	Total shots, breakdown by profile
get_shot_data_for_analysis	Full shot + profile for deep analysis
rate_shot	Mark a shot as like / dislike
search_historical_profiles	Find past profile versions

Grinder + diary

Tool	What it does
get_grinder_context	Recall saved grinder settings for all profiles
set_grinder_context	Save current grinder setting for a profile
read_diary	Read the full shot diary
append_diary_entry	Log a shot with tasting notes

---

Shot data verbosity

Shot tools default to compact responses to keep context windows manageable:

Option	What you get
verbosity: "summary"	Key metadata only
verbosity: "compact"	Metadata + sampled trace (default)
verbosity: "full"	Full raw payload

---

Full setup options

See LLM_SETUP.md for all installation paths — laptop, clone-and-build, and Raspberry Pi remote access.

---

Project layout

meticulous-mcp-server/
├── src/
│   ├── server.ts          # All 25 MCP tools + machine logic
│   ├── index.ts           # stdio entry point (laptop / Claude Desktop / Claude Code)
│   └── http.ts            # HTTP entry point (Pi / Cloudflare / claude.ai)
├── dist/                  # Compiled output
├── LLM_SETUP.md           # Setup guide for all install paths
├── PI_SETUP_INSTRUCTIONS.md  # Full Pi + Cloudflare Tunnel walkthrough
├── Justfile               # Build, run, deploy, test commands
└── pi-setup.sh            # Pi dependency installer

---

License

MIT — see LICENSE. Maintainer release steps are in RELEASING.md.