# Grasshopper MCP workflow

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

document:[https://www.autodesignlab.org/zh/blog/lecture-2025-rhino-mcp/](https://www.autodesignlab.org/en/blog/lecture-2025-rhino-mcp-p2/)

**Language Selection / 語言選擇**: [English](README.md) | [繁體中文](README.zh-TW.md)

## 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](https://github.com/alfredatnycu/grasshopper-mcp/raw/master/releases/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:
   
      ```json
      {
        "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:
      
      ```json
      {
        "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

```python
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

```bash
# 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](grasshopper_tools/docs/).

## 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](grasshopper_tools/docs/) 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/](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.