rhino-gh-mcp 0.1.8
Rhino and Grasshopper integration through the Model Context Protocol with uv package management
License: MIT
Requires Python: >=3.10

# 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):
   ```bash
   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**:
   ```bash
   cd rhino_gh_mcp_uv
   uv sync  # This creates a virtual environment and installs all dependencies
   ```

3. **Configure environment variables** (optional):
   ```bash
   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**:
```json
{
  "mcpServers": {
    "rhino-gh-mcp": {
      "command": "uvx",
      "args": ["rhino-gh-mcp"]
    }
  }
}
```

**For Local Development**:
```json
{
  "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

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