Grasshopper MCP workflow

Grasshopper MCP workflow is a bridging server that connects Grasshopper and Cursor using the Model Context Protocol (MCP) standard.

Language Selection / 語言選擇: English | 繁體中文

Features

• MCP Protocol Integration: Connects Grasshopper and Cursor through the Model Context Protocol (MCP) standard
• Component Management: Intuitive tool functions for creating, managing, and connecting Grasshopper components
• Intent Recognition: Supports high-level intent recognition, automatically creating complex component patterns from simple descriptions
• Component Knowledge Base: Includes a comprehensive knowledge base that understands parameters and connection rules for common components
• Workflow Automation: Provides tools for executing complex Grasshopper workflows from JSON and MMD files
• CLI Tools: Command-line interface for batch operations and automation
• Parameter Management: Advanced parameter setting and management capabilities
• Group Management: Organize components into groups with custom colors and names

System Architecture

The system consists of the following parts:

1. Grasshopper MCP Component (GH_MCP.gha): A C# plugin installed in Grasshopper that provides a TCP server to receive commands
2. Python MCP Bridge Server (grasshopper_mcp): A bridge server that connects Cursor and the Grasshopper MCP component
3. Grasshopper Tools (grasshopper_tools): A comprehensive Python library for managing Grasshopper components, connections, parameters, and workflows
4. Component Knowledge Base: JSON files containing component information, patterns, and intents
5. Workflow Skill (grasshopper-workflow): A specialized skill for Cursor that provides advanced workflow automation capabilities

Installation Instructions

Prerequisites

• Rhino 7 or higher
• Grasshopper
• Python 3.8 or higher
• Cursor

Installation Steps

1. Install the Grasshopper MCP Component

   Method 1: Download the pre-compiled GH_MCP.gha file (Recommended)

   Download the GH_MCP.gha file directly from the GitHub repository and copy it to the Grasshopper components folder:

   %APPDATA%\Grasshopper\Libraries\
   

   Method 2: Build from source

   If you prefer to build from source, clone the repository and build the C# project using Visual Studio.

2. Install the Python MCP Bridge Server

   Method 1: Install from PyPI (Recommended)

   The simplest method is to install directly from PyPI using pip:

   pip install grasshopper-mcp
   

   Method 2: Install from GitHub

   You can also install the latest version from GitHub:

   pip install git+https://github.com/alfredatnycu/grasshopper-mcp.git
   

   Method 3: Install from Source Code

   If you need to modify the code or develop new features, you can clone the repository and install:

   git clone https://github.com/alfredatnycu/grasshopper-mcp.git
   cd grasshopper-mcp
   pip install -e .
   

Usage

1. Start Rhino and Grasshopper

   Launch Rhino and open Grasshopper.

2. Add the GH_MCP Component to Your Canvas

   Find the GH_MCP component in the Grasshopper component panel and add it to your canvas.

3. Start the Python MCP Bridge Server

   Open a terminal and run:

   python -m grasshopper_mcp.bridge
   

   Note: The command grasshopper-mcp might not work directly due to Python script path issues. Using python -m grasshopper_mcp.bridge is the recommended and more reliable method.

4. Configure Cursor MCP Connection

   Configure the MCP server connection in Cursor to enable communication between Cursor and the Grasshopper MCP bridge server.

   Configuration Steps:

   1. Locate Cursor's MCP configuration file mcp.json, typically located at:

      • Windows: %APPDATA%\Cursor\User\mcp.json or ~\.cursor\mcp.json
      • macOS: ~/Library/Application Support/Cursor/User/mcp.json or ~/.cursor/mcp.json

   2. Add the following configuration to the mcp.json file:

      {
        "mcpServers": {
          "grasshopper": {
            "command": "python",
            "args": ["-m", "grasshopper_mcp.bridge"]
          }
        }
      }
      

   3. Using Virtual Environment or Specific Python Path:

      If you're using a virtual environment or conda environment, specify the full path to the Python executable:

      {
        "mcpServers": {
          "grasshopper": {
            "command": "C:\\Users\\YourUsername\\.conda\\envs\\grasshopper-mcp\\python.exe",
            "args": ["-m", "grasshopper_mcp.bridge"]
          }
        }
      }
      

      Tip: On Windows, backslashes in paths need to be escaped with double backslashes \\ or use forward slashes /.

   4. Verify Python Path:

      You can find the full path to your Python executable using:

      • Windows: where python or where python3
      • macOS/Linux: which python or which python3

      If using a conda environment, you can run:

      conda activate grasshopper-mcp
      where python  # Windows
      which python  # macOS/Linux
      

   5. After saving the configuration file, restart Cursor for the changes to take effect.

   Note: Make sure you have completed steps 2 (adding the GH_MCP component to the Grasshopper canvas) and step 3 (starting the Python MCP bridge server) before configuring MCP. The MCP bridge server needs to be running before Cursor can connect.

5. Start Using Grasshopper with Cursor

   You can now use Cursor to control Grasshopper through natural language commands.

Example Commands

Here are some example commands you can use with Cursor:

• "Create a circle with radius 5 at point (0,0,0)"
• "Connect the circle to an extrude component with a height of 10"
• "Create a grid of points with 5 rows and 5 columns"
• "Apply a random rotation to all selected objects"
• "Create a rectangle component and set its width to 10"
• "Group all selected components and name them 'Geometry Group'"

Using Grasshopper Tools

The project includes a comprehensive grasshopper_tools library for programmatic control of Grasshopper:

Python API Usage

from grasshopper_tools import (
    GrasshopperClient,
    ComponentManager,
    ConnectionManager,
    ParameterSetter,
    GroupManager
)

# Create client connection
client = GrasshopperClient(host="localhost", port=8080)

# Create component manager
comp_mgr = ComponentManager(client)

# Add a component
component_id = comp_mgr.add_component(
    guid="e2bb9b8d-0d80-44e7-aa2d-2e446f5c61da",  # Number Slider GUID
    x=100,
    y=200,
    component_id="SLIDER_WIDTH"
)

# Set component parameters
param_setter = ParameterSetter(client)
param_setter.set_slider_properties(
    component_id=component_id,
    value="10",
    min_value=0,
    max_value=100
)

CLI Usage

# Execute a placement workflow from JSON
python -m grasshopper_tools.cli execute-placement GH_WIP/placement_info.json

# Parse MMD files
python -m grasshopper_tools.cli parse-mmd GH_WIP/component_info.mmd --action sliders

# View help
python -m grasshopper_tools.cli --help

For more detailed documentation, see the grasshopper_tools documentation.

Troubleshooting

If you encounter issues, check the following:

1. GH_MCP Component Not Loading

   • Ensure the .gha file is in the correct location: %APPDATA%\Grasshopper\Libraries\
   • In Grasshopper, go to File > Preferences > Libraries and click "Unblock" to unblock new components
   • Restart Rhino and Grasshopper
   • Check that you have the correct .NET runtime installed (net48 or net7.0)

2. Bridge Server Won't Start

   • If grasshopper-mcp command doesn't work, use python -m grasshopper_mcp.bridge instead
   • Ensure all required Python dependencies are installed: pip install -r requirements.txt
   • Check if port 8080 is already in use by another application
   • Verify Python version is 3.8 or higher: python --version

3. Cursor Can't Connect

   • Ensure the bridge server is running
   • Verify you're using the correct connection settings (localhost:8080)
   • Check the console output of the bridge server for any error messages
   • Ensure the GH_MCP component is added to your Grasshopper canvas
   • Check that Cursor's MCP configuration is correct

4. Commands Not Executing

   • Verify the GH_MCP component is on your Grasshopper canvas
   • Check the bridge server console for error messages
   • Ensure Cursor is properly connected to the bridge server
   • Verify the component GUIDs are correct when using grasshopper_tools

5. Grasshopper Tools Issues

   • Ensure you're using the correct host and port (default: localhost:8080)
   • Check that the MCP bridge server is running before using the tools
   • Verify file paths when using CLI commands
   • See grasshopper_tools documentation for detailed troubleshooting

Development

Project Structure

grasshopper-mcp/
├── grasshopper_mcp/           # Python MCP bridge server
│   ├── __init__.py
│   └── bridge.py              # Main bridge server implementation
├── grasshopper_tools/          # Python tools library
│   ├── client.py              # MCP client implementation
│   ├── component_manager.py  # Component management
│   ├── connection_manager.py  # Connection management
│   ├── parameter_setter.py    # Parameter setting utilities
│   ├── group_manager.py       # Group management
│   ├── placement_executor.py  # Workflow execution
│   ├── parser_utils.py        # MMD/JSON parsing
│   ├── cli.py                 # Command-line interface
│   └── docs/                  # Documentation
├── GH_MCP/                    # Grasshopper component (C#)
│   └── GH_MCP/
│       ├── Commands/          # Command handlers
│       ├── Models/            # Data models
│       ├── Utils/             # Utilities
│       └── Resources/         # Component knowledge base
├── grasshopper-workflow/      # Workflow skill for Cursor
│   ├── references/           # API references
│   ├── scripts/              # Workflow scripts
│   └── SKILL.md              # Skill documentation
├── GH_WIP/                    # Work in progress files
│   ├── component_info.mmd    # Component information
│   ├── part_info.mmd         # Part information
│   └── placement_info.json   # Placement workflow
├── scripts/                   # Utility scripts
├── prompt/                    # Prompt templates
├── docs/                      # Project documentation
├── releases/                  # Pre-compiled binaries
│   └── GH_MCP.gha            # Compiled Grasshopper component
├── setup.py                   # Python package setup
├── requirements.txt           # Python dependencies
└── README.md                  # This file

Additional Resources

• Grasshopper Tools Documentation: See grasshopper_tools/docs/ for detailed API documentation and usage guides
• Workflow Skill: The grasshopper-workflow skill provides advanced workflow automation capabilities for Cursor
• Example Scripts: Check the scripts/ directory for example usage scripts
• Prompt Templates: The prompt/ directory contains prompt templates for various workflow steps

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

When contributing:

• Follow the existing code style and structure
• Add documentation for new features
• Include tests when possible
• Update this README if adding new features or changing installation steps

Changelog

Version 0.1.0

Release Date: 2024-12-19

• Initial release of Grasshopper MCP Bridge
• Support for MCP protocol integration with Cursor
• Component management and connection tools
• Intent recognition for automatic component pattern creation
• Comprehensive component knowledge base
• Workflow automation from JSON and MMD files
• CLI tools for batch operations
• Parameter and group management capabilities

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Thanks to the Rhino and Grasshopper community for their excellent tools
• Thanks to Cursor and the MCP protocol support

Contact

For questions or support, please open an issue on the GitHub repository.