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:

Grasshopper MCP Component (GH_MCP.gha): A C# plugin installed in Grasshopper that provides a TCP server to receive commands
Python MCP Bridge Server (grasshopper_mcp): A bridge server that connects Cursor and the Grasshopper MCP component
Grasshopper Tools (grasshopper_tools): A comprehensive Python library for managing Grasshopper components, connections, parameters, and workflows
Component Knowledge Base: JSON files containing component information, patterns, and intents
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

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.
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

Start Rhino and Grasshopper

Launch Rhino and open Grasshopper.
Add the GH_MCP Component to Your Canvas

Find the GH_MCP component in the Grasshopper component panel and add it to your canvas.
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.
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.
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:

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)
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
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
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
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.

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:

Grasshopper MCP Component (GH_MCP.gha): A C# plugin installed in Grasshopper that provides a TCP server to receive commands
Python MCP Bridge Server (grasshopper_mcp): A bridge server that connects Cursor and the Grasshopper MCP component
Grasshopper Tools (grasshopper_tools): A comprehensive Python library for managing Grasshopper components, connections, parameters, and workflows
Component Knowledge Base: JSON files containing component information, patterns, and intents
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

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.
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

Start Rhino and Grasshopper

Launch Rhino and open Grasshopper.
Add the GH_MCP Component to Your Canvas

Find the GH_MCP component in the Grasshopper component panel and add it to your canvas.
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.
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.
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:

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)
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
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
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
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.

Grasshopper MCP Workflow

Grasshopper MCP workflow

Features

System Architecture

Installation Instructions

Prerequisites

Installation Steps

Usage

Example Commands

Using Grasshopper Tools

Python API Usage

CLI Usage

Troubleshooting

Development

Project Structure

Additional Resources

Contributing

Changelog

Version 0.1.0

License

Acknowledgments

Contact

Grasshopper MCP workflow

Features

System Architecture

Installation Instructions

Prerequisites

Installation Steps

Usage

Example Commands

Using Grasshopper Tools

Python API Usage

CLI Usage

Troubleshooting

Development

Project Structure

Additional Resources

Contributing

Changelog

Version 0.1.0

License

Acknowledgments

Contact