# BambuStudio MCP Server
A comprehensive MCP (Model Context Protocol) server for Claude macOS app that provides **end-to-end 3D printing automation** with Bambu Lab printers - from natural language requirements to perfect printed objects.
## What This Does
Tell Claude what you need, and it will:
1. **Generate** a 3D model from your description
2. **Scale** it to your exact dimensions
3. **Slice** it with optimized parameters
4. **Print** it on your Bambu printer
5. **Monitor** the print via camera
6. **Detect** any issues and suggest fixes
7. **Learn** from each print to improve the next one
## Example Workflow
```
You: "I need a tube squeezer for my Gold Bond lotion bottle, it's about 65mm diameter"
Claude:
1. Parses requirements → tube_squeezer, 65mm, heavy_duty
2. Generates parametric model with CadQuery
3. Adjusts for larger size (thicker walls, more infill)
4. Slices with BambuStudio CLI
5. Monitors print via RTSPS camera
6. Records outcome: 88% quality, minor stringing
7. Recommends: +0.5mm retraction, -5°C nozzle temp
```
## Features
### Phase 0: Model Generation (NEW!)
- **Natural Language Parsing**: "I need a squeezer for 65mm bottle" → structured parameters
- **Image Analysis**: Extract dimensions from photos with rulers
- **Parametric Generation**: CadQuery/OpenSCAD for precise functional parts
- **Template Library**: Pre-built customizable designs (squeezers, holders, clips)
- **AI Generation**: Text-to-3D via Meshy/Tripo3D for organic shapes
### Phase 1: Model Preparation
- **Model Analysis**: Load and analyze STL/3MF files, extract dimensions
- **Smart Scaling**: Scale based on target dimensions (toothpaste → lotion bottle)
- **Parameter Optimization**: Adjust slicing for scaled prints
### Phase 2: Print Execution & Monitoring
- **Printer Control**: MQTT connection to Bambu A1/A1 Mini in LAN mode
- **Camera Streaming**: RTSPS feed at 1 FPS
- **Defect Detection**: Layer shifts, stringing, warping, spaghetti detection
### Phase 3: Iterative Improvement
- **Print History**: SQLite database of all attempts
- **Recommendation Engine**: Learn from defects to suggest fixes
- **Quality Scoring**: 0-100 score based on detected issues
### Novice-Friendly Features (NEW!)
- **Interactive Wizard**: Guided workflow with checkpoints for beginners
- **Plain Language Support**: "heavy duty" → thick walls, high infill
- **Design Review**: Catches issues before you print (thin walls, tight clearances)
- **Slicing Review**: Recommends settings based on use case (functional vs decorative)
- **Material Optimization**: Auto-adjusts for your specific filament
## Supported Materials
Pre-configured profiles for:
- **Bambu Basic PLA** - General purpose, 220°C nozzle, up to 300mm/s
- **Bambu PETG Translucent** - Functional parts, 250°C nozzle
- **Prusament PC Blend** - High strength, 270°C nozzle (keep parts small on A1)
- **Generic PETG** - Outdoor/water-resistant, 245°C nozzle
- **Generic TPU 95A** - Flexible, 230°C nozzle, 40mm/s max, **NO AMS**
## Supported Nozzles
All A1/A1 Mini nozzle configurations:
- **0.2mm Stainless Steel** - Fine detail, miniatures
- **0.4mm Stainless Steel** - Default, best all-around
- **0.4mm Hardened Steel** - For carbon fiber/glow filaments
- **0.6mm Hardened Steel** - Faster prints, functional parts
- **0.8mm Hardened Steel** - Draft prints, large parts
## Requirements
- macOS with BambuStudio installed
- Bambu Lab A1/A1 Mini printer in LAN mode
- Python 3.10+
- Printer access code (from printer settings)
## Installation
```bash
cd bambustudio-mcp
# Basic installation
pip install -e . --break-system-packages
# With CAD generation (recommended)
pip install -e ".[cad]" --break-system-packages
# With everything
pip install -e ".[all]" --break-system-packages
```
## Configuration
This project uses [1Password CLI](https://developer.1password.com/docs/cli/) for secure secret management. Never store API keys or credentials in plain text files.
### Setting Up 1Password CLI
1. Install 1Password CLI:
```bash
brew install --cask 1password-cli
```
2. Sign in and enable shell integration:
```bash
op signin
```
3. Store your secrets in 1Password. Create items with these fields:
- **Bambu Printer**: `ip_address`, `access_code`, `serial_number`
- **Meshy** (optional): `api_key`
- **Tripo3D** (optional): `api_key`
### Running with 1Password CLI
Use `op run` to inject secrets as environment variables:
```bash
op run --env-file=.env.template -- python -m bambustudio_mcp
```
Create a `.env.template` file (safe to commit - contains only references, not secrets):
```bash
# Printer connection (required)
BAMBU_PRINTER_IP=op://Personal/Bambu Printer/ip_address
BAMBU_ACCESS_CODE=op://Personal/Bambu Printer/access_code
BAMBU_SERIAL=op://Personal/Bambu Printer/serial_number
# BambuStudio path (usually auto-detected)
BAMBUSTUDIO_PATH=/Applications/BambuStudio.app/Contents/MacOS/BambuStudio
# Optional: AI 3D generation
MESHY_API_KEY=op://Personal/Meshy/api_key
TRIPO3D_API_KEY=op://Personal/Tripo3D/api_key
```
## Claude Desktop Configuration
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"bambustudio": {
"command": "op",
"args": [
"run",
"--env-file=/path/to/bambustudio-mcp/.env.template",
"--",
"python",
"-m",
"bambustudio_mcp"
]
}
}
}
```
This ensures secrets are never stored in plain text and are securely injected at runtime.
## Available Tools (33 total)
### Novice-Friendly Wizard Tools (NEW!)
| Tool | Description |
|------|-------------|
| `bambustudio_start_guided_workflow` | **Start here!** Interactive workflow with checkpoints |
| `bambustudio_parse_novice_description` | Translate "heavy duty" → technical parameters |
| `bambustudio_review_design` | Get design suggestions before generating |
| `bambustudio_review_slicing` | Get quality settings for your material/use case |
| `bambustudio_optimize_for_material` | Auto-optimize parameters for your filament |
| `bambustudio_list_materials` | List supported filaments with properties |
| `bambustudio_list_nozzles` | List A1 nozzles with recommendations |
| `bambustudio_get_nozzle_recommendation` | Get best nozzle for your needs |
### Model Generation
| Tool | Description |
|------|-------------|
| `bambustudio_parse_requirements` | Parse natural language → structured parameters |
| `bambustudio_analyze_reference_image` | Extract dimensions from photos |
| `bambustudio_list_templates` | List available model templates |
| `bambustudio_generate_from_template` | Generate from customizable template |
| `bambustudio_generate_parametric` | Generate from description (CadQuery) |
| `bambustudio_ai_generate` | AI text-to-3D (Meshy/Tripo3D) |
| `bambustudio_ai_status` | Check AI generation progress |
### Model Preparation
| Tool | Description |
|------|-------------|
| `bambustudio_analyze_model` | Analyze STL/3MF dimensions and quality |
| `bambustudio_scale_model` | Scale model to target dimensions |
| `bambustudio_slice_model` | Slice with BambuStudio CLI |
| `bambustudio_list_presets` | List slicing presets |
### Printer Control
| Tool | Description |
|------|-------------|
| `bambustudio_test_printer_connection` | Test MQTT connection |
| `bambustudio_get_printer_status` | Get temperatures, progress |
| `bambustudio_control_print` | Pause/resume/stop print |
### Camera & Quality
| Tool | Description |
|------|-------------|
| `bambustudio_capture_camera` | Capture camera frames |
| `bambustudio_analyze_print_quality` | Detect defects in frame |
### Iteration Tracking
| Tool | Description |
|------|-------------|
| `bambustudio_create_iteration` | Start tracking a print |
| `bambustudio_record_outcome` | Record result + defects |
| `bambustudio_get_recommendations` | Get parameter fixes |
| `bambustudio_get_model_history` | View print history |
## Architecture
```
bambustudio_mcp/
├── server.py # MCP server with all 33 tools
├── config.py # Environment configuration
├── materials/ # NEW: Filament & nozzle profiles
│ ├── filaments.py # 5 pre-configured filament profiles
│ └── nozzles.py # A1 nozzle configurations
├── wizard/ # NEW: Novice-friendly workflow
│ ├── guided_workflow.py # Interactive checkpoints
│ ├── design_review.py # Design suggestions
│ ├── slicing_review.py # Quality recommendations
│ ├── novice_parser.py # Plain language → parameters
│ └── material_optimizer.py # Material-based adjustments
├── generator/ # Model generation
│ ├── requirements.py # Natural language parsing
│ ├── image_analyzer.py # Photo dimension extraction
│ ├── parametric.py # CadQuery/OpenSCAD generation
│ ├── templates.py # Template library
│ └── ai_generator.py # Meshy/Tripo3D integration
├── models/
│ ├── analyzer.py # STL/3MF analysis
│ └── scaler.py # Dimension scaling
├── slicer/
│ ├── cli.py # BambuStudio CLI
│ ├── parameters.py # Slicing parameters
│ └── profiles.py # Preset management
├── printer/
│ ├── mqtt_client.py # MQTT communication
│ ├── controller.py # Job control
│ └── status.py # Status parsing
├── camera/
│ ├── stream.py # RTSPS capture
│ └── detector.py # Defect detection
└── iteration/
├── tracker.py # SQLite history
└── recommender.py # Parameter recommendations
```
## Novice-Friendly Usage
For CAD beginners, use the guided workflow:
```python
# Start with your plain language description
workflow = await bambustudio_start_guided_workflow({
"description": "I need a heavy duty squeezer for my 65mm lotion bottle"
})
# The system parses your description:
# - "heavy duty" → wall_thickness: 3mm, infill: 30%
# - "65mm" → tube_diameter: 65mm
# - "squeezer" → category: tube_squeezer
# Then guides you through checkpoints:
# 1. Requirements confirmation
# 2. Design review (catches thin walls, tight tolerances)
# 3. Material selection (suggests TPU if flexible needed)
# 4. Nozzle selection (recommends 0.4mm for standard parts)
# 5. Quality settings (functional vs decorative)
# 6. Final review before generation
```
### Plain Language Examples
The system understands:
- "heavy duty" → thick walls (3mm), high infill (30%)
- "snug fit" → clearance: 0.2-0.3mm
- "loose fit" → clearance: 0.8-1.0mm
- "flexible" → suggests TPU material
- "waterproof" → suggests PETG
- "heat resistant" → suggests PC or PETG
## Examples
See `examples/` directory:
- `complete_workflow.py` - Full end-to-end example
- `tube_squeezer_workflow.py` - Scaling example
- `generation_tools_reference.md` - Generation tool docs
- `mcp_tools_reference.md` - All tools reference
## License
MIT
