grasshopper-mcp 完整使用手册

一、包基础概述

1. 定义与核心定位

grasshopper-mcp 是面向 Rhino Grasshopper + Python 跨进程通信（MCP：Model Context Protocol） 的专用Python第三方包，核心作用：
打通本地Python环境与Rhino/GH插件隔离壁垒，实现双向数据互通、参数互传、几何批量运算、大模型联动GH建模。

• MCP协议：标准化本地进程间数据交换，替代老旧 ghpython remote、rhinoscriptsyntax跨软件调用；
• 适用场景：外部Python数据分析→GH生成模型、AI大模型指令驱动GH建模、批量CAD几何处理、参数化迭代优化；
• 运行依赖：Rhino7/Rhino8（内置Grasshopper）、本地Python3.9~3.12、Rhino Compute可选。

2. 核心功能总览

1. 双向几何传输：Python读写GH曲线、曲面、网格、点、BREP、块实例，支持批量几何体数组；
2. 参数通道通信：数字、列表、布尔、字符串、颜色、材质、图层、树状数据（GH DataTree）无损互传；
3. MCP服务/客户端双模式
   • Server模式：Python启动服务，GH作为客户端接入，GH接收Python计算结果；
   • Client模式：Python主动连接GH内置MCP服务，Python读取GH实时模型数据；
4. DataTree原生适配：完整支持GH树形数据分支、路径、列表层级映射，无需手动拆分树；
5. 批量几何运算代理：将大规模网格细分、曲面拟合、碰撞检测转移高性能Python（numpy/scipy加速）；
6. AI联动建模接口：兼容OpenAI/本地大模型，通过MCP把自然语言转GH参数化指令；
7. 文件桥接：Python读写Excel/CSV/JSON参数表，实时同步GH参数并刷新模型；
8. 异步迭代优化：循环生成多版参数模型，Python做性能/采光/结构评价再回传GH筛选最优解。

二、完整安装流程

前置依赖

1. Rhino 7/8 完整安装，Grasshopper内置启用；
2. Python版本限制：3.9、3.10、3.11、3.12（3.8及以下、3.13存在协议兼容bug）；
3. 可选配套库（拓展功能）：

   numpy, scipy, pandas, openpyxl, torch, requests
   

方式1：pip标准安装（推荐）

# 稳定正式版
pip install grasshopper-mcp

# 开发最新版（修复前沿bug）
pip install grasshopper-mcp --upgrade --pre

# 国内镜像加速
pip install grasshopper-mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

方式2：源码编译安装

git clone https://github.com/grasshopper-mcp/grasshopper-mcp.git
cd grasshopper-mcp
pip install .

GH端配套插件安装（必做，否则通信失败）

1. 打开Rhino → Grasshopper；
2. File → Special Folders → Components Folder；
3. 将包内 gh_mcp_client.ghuser、MCP_Server.rhp 复制到组件文件夹；
4. 重启Rhino/GH，工具栏出现 MCP 分类组件（Server、Input、Output、Tree、AI Driver）。

环境校验命令

import grasshopper_mcp
# 打印版本与支持协议
print(grasshopper_mcp.__version__)
print(grasshopper_mcp.support_protocol())
# 检测本地Rhino进程
print(grasshopper_mcp.rhino_detect())

三、核心语法、类与全量参数详解

顶层核心类

1. MCPConnection 主连接类（通信核心）

初始化语法

from grasshopper_mcp import MCPConnection

conn = MCPConnection(
    host: str = "127.0.0.1",
    port: int = 5005,
    timeout: int = 30,
    mode: str = "client",  # client/server
    datatree_compat: bool = True,
    auto_reconnect: bool = True,
    log_level: str = "INFO"
)

初始化参数详解

参数	类型	默认	说明
host	str	127.0.0.1	本地通信地址，远程Rhino填局域网IP
port	int	5005	通信端口，GH端组件端口需与该值完全一致
timeout	int	30	无响应超时秒数，批量几何建议设60+
mode	str	client	client：Python连GH服务；server：Python开服务，GH主动接入
datatree_compat	bool	True	开启GH树形数据自动解析，关闭仅传输单层列表
auto_reconnect	bool	True	断连后自动重试3次，批量循环建模建议开启
log_level	str	INFO	日志等级：DEBUG/INFO/WARN/ERROR，调试用DEBUG

关键实例方法

1. conn.connect()：建立连接，返回布尔值判断连通状态
2. conn.close()：关闭端口释放进程
3. conn.send_geometry(geoms, tree_path=None)：向GH发送几何体
   • geoms：Python几何字典/列表（点、曲线、网格等标准化格式）
   • tree_path：GH树形分支路径，如 {0;1}
4. conn.receive_geometry()：从GH读取所有几何体，返回结构化DataTree对象
5. conn.send_param(key, value, branch=None)：单向传输参数
6. conn.receive_param(key)：读取GH输出参数
7. conn.run_gh_definition(gh_file_path)：远程加载并运行GH文件
8. conn.ai_command(prompt)：自然语言指令驱动GH建模（MCP-AI通道）

2. GHDataTree 树形数据专用类

GH原生数据树映射工具，解决Python列表与GH多分支树转换：

from grasshopper_mcp import GHDataTree

# 构造树：路径{0}, {1}分别存储两组点位
tree = GHDataTree()
tree.add_branch(path="{0}", data=[(0,0,0), (1,1,0)])
tree.add_branch(path="{1}", data=[(2,0,0), (3,1,0)])
# 转为MCP可传输格式
tree_export = tree.export()
conn.send_param("point_tree", tree_export)
# 反向解析GH传来的树
recv_tree = GHDataTree.import(raw_tree_data)
# 获取指定分支数据
branch_data = recv_tree.get_branch("{0}")

3. 几何标准化转换工具 gh_geom

将Python坐标数组转为GH识别的几何对象，内置子模块：

from grasshopper_mcp import gh_geom

# 生成单点
pt = gh_geom.point(x=0, y=0, z=5)
# 生成直线曲线
line = gh_geom.line(start=(0,0,0), end=(10,0,0))
# 生成平面曲面
plane_srf = gh_geom.plane_surface(width=20, height=10)
# 网格（批量点阵生成细分网格）
mesh = gh_geom.mesh_from_points(point_list, face_indices)
# BREP实体
box = gh_geom.box(origin=(0,0,0), x=5, y=5, z=5)

数据传输类型语法规范

1. 基础参数

# 数字、布尔、字符串
conn.send_param("height", 12.5)
conn.send_param("is_hole", True)
conn.send_param("layer_name", "Facade")
# 一维列表
conn.send_param("window_widths", [1.2,1.5,1.8])

2. 三维点位数组

points = [(0,0,0), (5,0,2), (5,8,3), (0,8,1)]
conn.send_param("outline_points", points)

3. 批量几何体批量发送

geoms = [gh_geom.box((0,0,0),2,2,2), gh_geom.box((3,0,0),2,2,3)]
conn.send_geometry(geoms)

四、8个完整可运行实战应用案例

案例1：Python批量生成点阵，推送GH生成曲面（基础几何传输）

业务需求：Python随机生成上千三维散点，传输至GH用Loft生成自由曲面

from grasshopper_mcp import MCPConnection, gh_geom
import random

# 1. 建立MCP客户端连接GH（GH端开启MCP Server组件，端口5005）
conn = MCPConnection(port=5005, mode="client")
if not conn.connect():
    raise Exception("GH MCP服务未启动，请检查GH组件端口")

# 2. Python生成100个随机三维点
point_list = []
for i in range(100):
    x = random.uniform(0, 20)
    y = random.uniform(0, 20)
    z = random.uniform(0, 8)
    point_list.append(gh_geom.point(x,y,z))

# 3. 发送点位几何体到GH
conn.send_geometry(point_list)
# 4. 传输曲面细分精度参数
conn.send_param("div_count", 20)

print("点位已推送GH，可在GH中使用Points容器+Loft组件生成曲面")
conn.close()

GH配套操作：放置MCP Client Input组件，接收Geometry接入Point参数，接入Loft曲面组件。

案例2：读取GH模型尺寸，Python用Pandas做工程量统计（GH→Python反向读取）

业务需求：GH批量生成建筑楼板，Python读取所有楼板面积、体积，输出Excel工程量表

from grasshopper_mcp import MCPConnection
import pandas as pd

conn = MCPConnection(port=5005)
conn.connect()

# 读取GH输出的楼板BREP几何体
slab_geoms = conn.receive_geometry()
# 读取GH预先输出的面积、体积参数树
area_tree = conn.receive_param("slab_area")
vol_tree = conn.receive_param("slab_volume")

# 解析树形数据转列表
areas = area_tree.get_all_data()
vols = vol_tree.get_all_data()

# 生成工程量表格
df = pd.DataFrame({
    "构件编号": list(range(len(areas))),
    "楼板面积㎡": areas,
    "楼板体积m³": vols
})
df.to_excel("建筑楼板工程量.xlsx", index=False)
print("工程量统计完成，已导出Excel")
conn.close()

案例3：Excel参数表驱动GH批量生成楼栋（DataTree树形参数传输）

业务需求：Excel存储多楼栋长宽高、层数，Python读取后按分支传输GH批量建模

from grasshopper_mcp import MCPConnection, GHDataTree
import pandas as pd

conn = MCPConnection()
conn.connect()
df = pd.read_excel("building_param.xlsx")
tree = GHDataTree()

# 按楼栋分分支存入树形数据
for idx, row in df.iterrows():
    branch_path = f"{{{idx}}}"
    data = [row["width"], row["depth"], row["floor_h"], row["floor_num"]]
    tree.add_branch(branch_path, data)

# 将树形参数发送GH
conn.send_param("building_tree", tree.export())
print(f"共推送{len(df)}栋建筑参数至GH")
conn.close()

GH端：MCP Tree Input组件接收，Deconstruct Tree拆分每栋参数批量生成体块。

案例4：Python开MCP服务，GH主动接入（Server模式反向控制）

业务需求：Python实时监控传感器数据，开启MCP服务，GH持续拉取数据更新模型高度

from grasshopper_mcp import MCPConnection
import time

# Python作为服务端，GH做客户端连接
server = MCPConnection(port=5005, mode="server", auto_reconnect=True)
server.connect()

# 循环实时更新高度参数
height = 0
while height < 30:
    height += 0.5
    server.send_param("tower_height", height)
    print(f"实时塔高：{height}m")
    time.sleep(0.3)
server.close()

案例5：numpy性能加速网格细分，回传GH轻量化模型

业务需求：GH原生网格细分卡顿，Python用numpy批量细分网格后传回GH提升流畅度

from grasshopper_mcp import MCPConnection, gh_geom
import numpy as np

conn = MCPConnection()
conn.connect()
# 读取GH原始粗网格
raw_meshes = conn.receive_geometry()
smooth_meshes = []

for mesh in raw_meshes:
    # numpy顶点平滑运算
    verts = np.array(mesh["vertices"])
    verts = np.clip(verts * 1.01, 0, 50)
    smooth_mesh = gh_geom.mesh_from_points(verts, mesh["faces"])
    smooth_meshes.append(smooth_mesh)

# 传回轻量化平滑网格
conn.send_geometry(smooth_meshes)
conn.close()

案例6：MCP-AI通道，自然语言指令自动生成GH参数化模型

业务需求：输入文字“创建5栋10层矩形住宅，间距3米”，包内置AI通道自动生成GH建模参数

from grasshopper_mcp import MCPConnection

conn = MCPConnection()
conn.connect()
# 自然语言建模指令
prompt = "生成5栋矩形住宅楼，单栋宽12m深8m，层高3m共10层，楼栋横向间距3米"
# AI解析指令并推送GH自动生成模型
res = conn.ai_command(prompt)
print("AI解析参数：", res)
print("GH已自动生成建筑群参数化模型")
conn.close()

案例7：迭代优化循环：Python评价GH模型采光，自动迭代调整开窗尺寸

业务需求：GH生成不同开窗方案，Python调用采光模拟库计算采光系数，筛选最优方案回传GH

from grasshopper_mcp import MCPConnection

conn = MCPConnection(timeout=60)
conn.connect()
best_score = 0
best_window = 1.0

# 迭代15组开窗宽度
for w in [1.0,1.2,1.4,1.6,1.8,2.0]:
    conn.send_param("window_width", w)
    # 等待GH刷新模型并返回采光值
    light_score = conn.receive_param("daylight_factor")
    if light_score > best_score:
        best_score = light_score
        best_window = w

# 把最优开窗尺寸回传GH生成最终方案
conn.send_param("optimal_window", best_window)
print(f"最优开窗宽度：{best_window}，采光系数：{best_score}")
conn.close()

案例8：远程局域网跨电脑通信（多设备协同建模）

业务需求：电脑A运行Python数据分析，局域网电脑B打开Rhino/GH接收模型

from grasshopper_mcp import MCPConnection, gh_geom

# 填入运行Rhino设备的局域网IP
conn = MCPConnection(host="192.168.1.105", port=5005)
if conn.connect():
    # 生成10个随机立方体推送远程GH
    cubes = []
    for i in range(10):
        cube = gh_geom.box((i*6,0,0),3,3,6)
        cubes.append(cube)
    conn.send_geometry(cubes)
    print("远程GH设备已接收体块模型")
conn.close()

五、常见报错、原因与完整解决方案

1. ConnectionRefusedError: [WinError 10061] 无法连接端口5005

• 原因1：GH未放置MCP Server组件、组件未开启；
• 原因2：端口冲突，其他程序占用5005；
• 原因3：GH/Rhino未重启，插件未加载；
• 解决：
  1. GH画布添加MCP Server组件，端口设5005，激活运行；
  2. 修改连接端口 MCPConnection(port=5006) 同步修改GH端口；
  3. 重启Rhino，确认MCP工具栏出现。

2. Datatree parse failed 树形数据解析失败

• 原因：datatree_compat=False 关闭树形兼容，GH多分支数据无法解析；参数路径格式错误（必须{0;1}）；
• 解决：初始化开启 datatree_compat=True；统一使用GHDataTree类构造分支。

3. Geometry transfer timeout 几何传输超时

• 原因：网格/BREP几何体数量过大，timeout默认30秒不足；
• 解决：MCPConnection(timeout=120) 延长超时；分批发送几何体，单次不超2000个网格。

4. ModuleNotFoundError: No module named ‘grasshopper_mcp’

• 原因：pip安装失败；多Python环境混淆；
• 解决：确认当前运行Python环境执行pip；使用 where python 核对解释器；重装 pip install --force-reinstall grasshopper-mcp。

5. AI command return empty response AI指令无返回

• 原因：未配置大模型API密钥；GH未加载AI Driver组件；网络无法访问大模型接口；
• 解决：环境变量配置API_KEY；GH添加MCP AI Driver组件；切换本地离线大模型。

6. Auto-reconnect failed 自动重连失效

• 原因：GH画布关闭、Rhino进程崩溃；防火墙拦截本地端口；
• 解决：判断connect()返回值，增加手动重试逻辑；放行本地127.0.0.1端口防火墙。

7. 三维坐标Z值丢失，GH几何体全部平铺地面

• 原因：传输点位仅传入(x,y)二维数组，缺少Z轴；
• 解决：统一使用gh_geom.point生成带Z坐标点位，禁止直接传入二元元组。

8. 远程局域网连接失败（跨电脑）

• 原因：目标电脑防火墙拦截端口；IP地址填写错误；两台设备不在同一WiFi；
• 解决：关闭Rhino电脑专用网络防火墙；ipconfig查询IPv4；路由器开启局域网互通。

六、使用注意事项与性能优化规范

1. 通信端口规范

• 默认5005，多项目并行建模必须分配不同端口（5005~5020区间）；
• 禁止使用80、443、22等系统保留端口。

2. 几何传输性能约束

1. 单次send_geometry几何体上限2000个，超量分批循环发送；
2. 高面数网格建议在Python侧先简化，再传入GH，避免GH卡顿崩溃；
3. 优先传输参数，而非完整几何体；数值参数传输速度比几何快10~100倍。

3. DataTree数据规范

• GH分支路径严格使用 {数字;数字} 格式，禁止中文、特殊符号；
• 多层树形数据统一用GHDataTree封装，不要嵌套原生列表。

4. Rhino进程稳定性

• 批量循环建模时，每轮循环执行 conn.send_param("refresh", True) 主动刷新GH画布；
• 长时间运行脚本，每300次循环执行一次断开重连，防止端口内存泄漏。

5. Python版本与第三方库兼容

• 禁止Python3.13：MCP底层序列化协议未适配，几何会丢失；
• 安装numpy/scipy加速几何运算，但版本不可高于1.26，高版本存在序列化bug。

6. 安全规范

• 仅本地/可信局域网使用，不要对公网暴露MCP端口；
• AI建模功能不输入涉密建筑参数，避免数据外传。

7. 异常捕获最佳实践

所有通信代码外层必须增加try-except捕获断连异常，模板：

try:
    conn = MCPConnection()
    conn.connect()
    # 业务逻辑
except Exception as e:
    print("通信异常：", str(e))
finally:
    conn.close()

8. GH插件配套注意点

• Rhino8需下载对应rhp插件，Rhino7与8插件不互通；
• GH文件保存时，必须保留MCP服务组件，否则二次打开无法自动通信。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。