🚀 Grasshopper MCP - AI-Powered Computational Design Assistant

An MCP (Model Context Protocol) server that brings AI capabilities directly into Rhino/Grasshopper workflows, featuring ML-based automatic layout optimization - a capability not found in any other publicly available tool.

🎯 What Makes This Different?

Unlike basic Grasshopper-to-LLM connectors that only generate code, this tool includes:

🧠 ML-Based Auto Layout (Industry First)

• DBSCAN clustering for automatic component grouping
• K-means clustering for fixed group counts
• User pattern learning with persistent preferences
• K-NN position prediction for optimal new component placement
• Wire crossing minimization algorithm

🎓 AI Mentoring System

• Performance prediction: Estimates optimization impact (e.g., "15-30% improvement expected")
• Pattern detection: Identifies inefficient patterns and suggests better alternatives
• Auto-grouping: Analyzes wire connectivity to suggest logical component groups
• Layout anomaly detection: Finds isolated, overlapping, or misaligned components

🔌 Live Rhino Integration

• Real-time connection to running Rhino/Grasshopper instances
• Execute Python code remotely in Rhino
• Get canvas state and trigger solves
• No file-based workflow required

📋 Features Overview

Category	Features
Rhino Bridge	Live connection, remote Python execution, canvas state
GH File Ops	Parse .gh/.ghx files, analyze structure, extract components
Component Library	Searchable database of 500+ GH components
Code Generation	GHPython and C# script templates
AI Mentoring	Performance prediction, alternatives, auto-grouping
ML Layout	Clustering, position prediction, crossing minimization

🛠️ Installation

git clone https://github.com/dongwoosuk/grasshopper-mcp.git
cd grasshopper-mcp
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -e .

⚙️ Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "grasshopper": {
      "command": "path/to/grasshopper_mcp/.venv/Scripts/python.exe",
      "args": ["-m", "grasshopper_mcp"],
      "cwd": "path/to/grasshopper_mcp"
    }
  }
}

🔌 Live Rhino Connection (Optional)

To enable real-time Rhino/Grasshopper control:

1. Open Rhino 7 or 8
2. Run EditPythonScript command
3. Open and run rhino_listener/rhino_bridge_listener.py
4. You'll see: Rhino Bridge Listener started on localhost:8080

📚 Available Tools

Rhino Bridge (requires listener)

Tool	Description
rhino_status	Check connection status
rhino_execute_python	Execute Python in Rhino
gh_canvas_state	Get current canvas state
gh_load_definition	Load a .gh file
gh_solve	Trigger recompute

AI Mentoring Tools

Tool	Description
predict_performance	Predict optimization impact
suggest_alternatives	Detect patterns, suggest better approaches
auto_group	Analyze connectivity, suggest groupings
ml_layout_analysis	ML clustering analysis
predict_component_position	K-NN based position prediction

Pattern Detection Examples

The suggest_alternatives tool detects these inefficient patterns:

Pattern	Better Alternative
Multiple Move components	Single Transform Matrix
Flatten + Graft sequence	Path Mapper
Python loops for geometry	Native GH components
Serial Boolean operations	Batch Boolean
Expression for simple math	Native Math components

🏗️ Architecture

grasshopper_mcp/
├── grasshopper_mcp/
│   ├── bridge.py              # Main MCP server
│   ├── rhino_bridge.py        # TCP client to Rhino
│   ├── gh_file_ops.py         # .gh/.ghx parsing
│   ├── component_library.py   # Component database
│   ├── code_generator.py      # Code templates
│   └── mentoring/
│       ├── ml_layout_learner.py        # DBSCAN/K-means
│       ├── advanced_layout_learner.py  # Advanced learning
│       ├── persistent_layout_learner.py # User patterns
│       ├── performance_predictor.py    # Optimization prediction
│       ├── alternative_suggester.py    # Pattern detection
│       ├── auto_grouper.py             # Wire-based grouping
│       ├── wire_crossing_detector.py   # Crossing detection
│       └── crossing_minimizer.py       # Layout optimization
├── rhino_listener/
│   └── rhino_bridge_listener.py  # Run IN Rhino
└── pyproject.toml

🤖 ML Layout System Details

How It Works

1. Feature Extraction: Analyzes component positions, types, and connections
2. Clustering: Groups components using DBSCAN or K-means
3. Pattern Learning: Stores user preferences in layout_preferences.json
4. Position Prediction: Uses K-NN to suggest optimal positions for new components
5. Anomaly Detection: Identifies layout issues (isolated nodes, overlaps, wrong flow direction)

Supported Analyses

# Example: ML clustering analysis
result = ml_layout_analysis(gh_file_path, method="dbscan")
# Returns: clusters, anomalies, optimization suggestions

# Example: Position prediction
result = predict_component_position(gh_file_path, "Panel", near_component="Slider")
# Returns: predicted X, Y coordinates based on learned patterns

🎯 Use Cases

• Design Automation: Let AI handle repetitive Grasshopper tasks
• Code Review: Get suggestions for optimizing definitions
• Learning: AI mentoring for Grasshopper best practices
• Layout Cleanup: Automatic organization of messy definitions
• Team Standards: Consistent component arrangement across projects

📄 License

MIT License - see LICENSE file.

🙏 Acknowledgments

• Built on the Model Context Protocol by Anthropic
• Grasshopper by David Rutten / McNeel
• scikit-learn for ML algorithms

📬 Contact

Dongwoo Suk - Computational Design Specialist

• GitHub: dongwoosuk
• LinkedIn: dongwoosuk