rhino-gh-mcp 0.1.8

Rhino and Grasshopper integration through the Model Context Protocol with uv package management

RhinoMCP with UV Package Management

RhinoMCP connects Rhino, Grasshopper and more to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Rhino + Grasshopper. This version uses UV for modern, fast package management and dependency resolution.

Features

Rhino Integration

• Two-way communication: Connect Claude AI to Rhino through a socket-based server
• Object manipulation and management: Create and modify 3D objects in Rhino including metadata
• Layer management: View and interact with Rhino layers
• Scene inspection: Get detailed information about the current Rhino scene (incl. screencapture)
• Code execution: Run arbitrary Python code in Rhino from Claude

Grasshopper Integration

• Code execution: Run arbitrary Python code in Grasshopper from Claude - includes the generation of gh components
• Canvas inspection: Get detailed information about your Grasshopper definition, including component graph and parameters
• Component management: Update script components, modify parameters, and manage code references
• External code integration: Link script components to external Python files for better code organization
• Real-time feedback: Get component states, error messages, and runtime information
• Non-blocking communication: Stable two-way communication via HTTP server

AI Integration

• Replicate API: Access thousands of AI models via API, including stable diffusion variants
• Web search: Integrated web search capabilities
• Email integration: Gmail integration for email search and management

Architecture

The system consists of three main components:

1. MCP Server (rhino_gh_mcp_uv/): Python server implementing the Model Context Protocol
2. Rhino Plugin (../rhino_script_client/rhino_client.py): Socket server running inside Rhino (port 9876)
3. Grasshopper Component (../rhino_gh_mcp/rhino_gh_mcpComponent.cs): C# Grasshopper component running HTTP server (port 9999)

Installation

Prerequisites

• Rhino 7 or newer
• Python 3.10 or newer
• UV package manager
• A Replicate API token (optional, for AI-powered features)

Setting up the Environment

1. Install UV (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   # or on Windows:
   # powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. Clone and setup the project:

   cd rhino_gh_mcp_uv
   uv sync  # This creates a virtual environment and installs all dependencies
   

3. Configure environment variables (optional):

   cp .env.sample .env
   # Edit .env file with your API tokens
   

Installing the Rhino Plugin

1. Build the Rhino Plugin:

   • Open ../rhino_script_client/rhino_script_client.sln in Visual Studio
   • Build the project to create the .rhp plugin file
   • The plugin will be installed automatically when Rhino starts

2. Start the Rhino MCP Service:

   • In Rhino, run the command ToggleMCPService or use the UI panel
   • The service will start a socket server on port 9876
   • Alternatively, you can run ../rhino_script_client/rhino_client.py directly in the Python Editor

Installing the Grasshopper Component

1. Build the Grasshopper Component:

   • Open ../rhino_gh_mcp/rhino_gh_mcp.sln in Visual Studio
   • Build the project to create the .gha component file
   • The component will be available in Grasshopper under the "MCP" tab

2. Start the Grasshopper MCP Server:

   • Open Grasshopper in Rhino
   • Add the "rhino_gh_mcp MCP Server" component to your canvas
   • Set the "RunServer" input to True to start the HTTP server on port 9999
   • Optionally set "CategoryFilter" to prioritize specific component categories (e.g., "MCP,Math") - this prioritizes components from these categories but allows access to all components

MCP Client Configuration

For Published Package:

{
  "mcpServers": {
    "rhino-gh-mcp": {
      "command": "uvx",
      "args": ["rhino-gh-mcp"]
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "rhino-gh-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/rhino_gh_mcp_uv", "python", "-m", "rhino_gh_mcp_uv.server"],
      "cwd": "/absolute/path/to/rhino_gh_mcp_uv"
    }
  }
}

Usage

Starting the Complete System

1. Start Rhino:

   • Open Rhino 7 or 8
   • Start the Rhino MCP service (see "Installing the Rhino Plugin" above)

2. Start Grasshopper MCP Server (optional, for Grasshopper features):

   • Open Grasshopper
   • Add the "rhino_gh_mcp MCP Server" component
   • Set "RunServer" to True

3. Start Claude Desktop or Cursor IDE:

   • The MCP server will be started automatically when needed
   • The connection between Claude/Cursor and Rhino/Grasshopper will be established automatically

Managing the Connection

• Stop the Rhino server: Run the ToggleMCPService command again or use the UI panel
• Stop the Grasshopper server: Set the "RunServer" input on the MCP Server component to False
• Check server status: Use the "Status" output on the Grasshopper component or check the Rhino command line
• Restart connections: Simply restart the respective components

Development

Adding Dependencies

uv add package-name          # Add dependency
uv add --dev package-name    # Add dev dependency
uv sync --upgrade           # Update all dependencies

Troubleshooting

Common Issues

1. UV not found: Make sure UV is installed and in your PATH
2. Port conflicts: Ensure ports 9876 (Rhino) and 9999 (Grasshopper) are available
3. Connection issues:
   • Check that the Rhino MCP service is running
   • Check that the Grasshopper MCP Server component has "RunServer" set to True
   • Verify both components are built and loaded correctly
4. Import errors: Run uv sync to ensure all dependencies are installed
5. Component not found: Make sure the Grasshopper component is built and the .gha file is in the correct location

License

MIT License - see LICENSE file for details.