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.