cloudHPC

cloudHPC MCP 服务

通过支持 Model Context Protocol (MCP) 的 AI 助手，在 cloudHPC 上运行工程仿真：Claude、ChatGPT/Codex、Gemini、GitHub Copilot 等。可从桌面应用、终端应用，以及（在支持的情况下）Web 应用使用。检查本地算例、获取 vCPU/RAM 建议、上传文件夹、启动任务、监控进度、诊断错误并下载结果，全程只需对话。

支持的求解器：cloudHPC 上提供的所有求解器（FDS、OpenFOAM、snappyHexMesh、DAFoam、code_aster、CalculiX、OpenRadioss/OpenCourant、SU2、openTELEMAC、LIGGGHTS、LAMMPS、OpenLB、Palabos、FreeFEM、T-Flows、DualSPHysics、OpenFOAM/CalculiX/code_aster 与 preCICE 耦合、EnergyPlus、CONTAM 等）。资源建议遵循 cloudHPC 可扩展性规则，运行诊断遵循 cloudHPC 错误指南。

• 你可以提出的问题
• 安全的入门提示词
• 工具
• 安装
• 连接 AI 助手
  • Claude · ChatGPT / Codex · Gemini · GitHub Copilot · 其他客户端
  • Web 应用（托管端点）
• 须知
• 故障排查

你可以提出的问题

• “检查此文件夹中的 FDS 算例，并告诉我应该使用哪些资源。”
• “在 cloudHPC 上运行，并在完成后下载结果。”
• “我正在运行的仿真目前状态如何？”
• “我上次运行失败了：出了什么问题？”
• “我的 OpenFOAM 运行收敛良好：将 endTime 延长到 2000，不要停止运行。”

安全的入门提示词

先从只读取数据的问题开始，熟悉助手的工作方式后，再执行需要付费的操作：

1. “如何为 cloudHPC 准备 OpenFOAM 算例？”（无需账户）
2. “列出我最近的仿真并总结其状态。”
3. “我上次的仿真为什么失败？检查日志。”
4. “对于包含 8 个网格和 200 万个单元的 FDS 模型，我应该使用哪种 vCPU 和 RAM？”
5. “我上次运行的存储文件夹中有什么？哪些文件是结果？”

之后再说：“上传此算例并启动”、“恢复仿真 1234”。每项需要付费或删除数据的操作都会先征求你的确认，助手也会向你说明将执行的操作。使用 OAuth 登录时，你还可以选择以只读访问权限连接（参见使用 OAuth 登录）。

工具

工具	功能
inspect_case ¹	检测本地文件夹中的求解器和模型规模（FDS 网格/MPI 组、OpenFOAM 单元、CalculiX 节点等），并运行预检
suggest_resources	推荐 vCPU 和 RAM 类型，并说明理由
solver_guide	介绍如何为求解器准备算例：输入文件、cloudHPC 自动执行的操作、重启、可选设置、并行处理和日志
list_solvers, list_machine_options	可用的求解器、vCPU 数量和 RAM 类型
upload_folder ¹	压缩本地算例文件夹并上传到你的存储空间
launch_simulation	启动一次运行（需要确认）
list_simulations, get_simulation, wait_for_simulation	跟踪你的运行；已完成的运行会附带已知错误的诊断结果
sync_simulation	上传正在运行的作业的部分结果
stop_simulation	软停止或硬停止（需要确认）
resume_simulation	使用相同的求解器、vCPU、RAM 类型和文件夹恢复已停止的运行（FDS 和 OpenFOAM；需要确认）
start_desktop	启动 Linux 或 Windows 远程桌面以进行后处理；在停止前会持续计费（需要确认）
live_settings	查看正在运行的模拟中可更改的内容、这些文件的当前内容以及先前实时更新的状态
update_running_simulation	无需停止即可更改正在运行的模拟：OpenFOAM system/controlDict、fvSolution、fvSchemes；FDS <CHID>.stop；code_saturne RESU/<run>/control_file；OpenRadioss/OpenCourant <root>_0001.ctl。文件会放入算例的 _push 文件夹，并自动请求同步，因此机器会在几分钟内应用这些文件（需要确认）
open_remote_desktop	正在运行的作业的浏览器远程桌面链接
list_storage, list_results	浏览你的存储空间和结果存档
download_results ¹	下载结果存档并在本地解压
get_upload_link, get_download_link	用于上传/下载单个文件的临时链接
delete_storage	删除文件或文件夹（需要确认）
api_usage	API 速率限制和已使用的调用次数

会产生费用或删除数据的操作（启动运行、硬停止、从存储空间删除）始终需要你确认。在支持此功能的应用中（例如 Claude Code），服务会直接显示确认对话框，因此助手无法代你确认；在其他应用中，助手会显示摘要并等待你确认。

¹ 仅适用于本地安装：这些工具会处理你电脑上的文件。在 Web 应用（托管端点）中，请改用 get_upload_link / get_download_link。

安装

要求：

• Python 3.10 或更高版本
• cloudHPC 账户及其 API 密钥：打开你的 cloudHPC 个人资料页面 （APIKEY 文档）。该密钥可完全访问你的账户，请妥善保密。

使用 pipx 安装（推荐：相互隔离，且命令会安装到 ~/.local/bin，方便桌面应用查找）：

pipx install git+https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp

或使用 pip 安装：

pip install git+https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp

这会安装 cloudhpc-mcp 命令。找到它的完整路径，后续可能会用到：

which cloudhpc-mcp          # Linux / macOS
where cloudhpc-mcp          # Windows

API 密钥会从 CLOUDHPC_APIKEY 环境变量读取；如果未设置，则从 cloudHPCexec 创建的 ~/.cfscloudhpc/apikey 文件读取。

连接 AI 助手

有两种连接方式：

• 本地安装（桌面和终端应用）：服务在你的计算机上运行，因此可以读取你的案例文件夹，并将结果保存在其旁边。所有工具均可用。推荐使用。
• 托管端点（Web 应用）：https://mcp.cloudhpc.cloud/mcp，无需安装。你只需使用 API 密钥登录一次（OAuth），或在请求头中发送密钥即可完成连接。它无法读取你计算机上的文件：你需要上传案例，并通过临时链接（或 cloudHPC Web 应用）下载结果。参见 Web 应用（托管端点）。

助手	桌面应用	终端（Linux）	Web 应用
Claude	Claude Desktop（Windows、macOS、Linux 测试版）	Claude Code	claude.ai（自定义连接器）
ChatGPT	ChatGPT 桌面应用（支持 MCP 服务的版本）	Codex CLI	ChatGPT（通过 OAuth 登录）
Gemini	不支持：没有支持 MCP 的 Gemini 桌面应用	Gemini CLI	Gemini（通过 OAuth 登录）
GitHub Copilot	VS Code（Copilot Agent 模式）	Copilot CLI	不支持

在每个示例中，将 your-api-key 替换为你的密钥。如果助手找不到 cloudhpc-mcp 命令，请改用其完整路径（参见安装）。

Claude

Claude Desktop

打开 设置 > 开发者 > 编辑配置，并将服务添加到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：使用 编辑配置 打开文件

{
  "mcpServers": {
    "cloudhpc": {
      "command": "cloudhpc-mcp",
      "env": { "CLOUDHPC_APIKEY": "your-api-key" }
    }
  }
}

重启 Claude Desktop。新对话的工具菜单中会显示 cloudHPC 工具。

Claude Code

claude mcp add --scope user cloudhpc -e CLOUDHPC_APIKEY=your-api-key -- cloudhpc-mcp

--scope user 会使其在每个文件夹中都可用。使用 claude mcp list 检查，或在 Claude Code 中输入 /mcp。

ChatGPT / Codex

ChatGPT 桌面应用

在较新版本的 ChatGPT 桌面应用中：选择 设置 > MCP 服务 > 添加服务，然后选择 STDIO：

• 命令：cloudhpc-mcp
• 环境变量：CLOUDHPC_APIKEY = your-api-key

该应用与 Codex 共用 MCP 配置（~/.codex/config.toml，见下文），因此在其中一个应用中添加的服务也可在另一个应用中使用。是否可用取决于应用版本和套餐。ChatGPT Web 应用仅支持远程连接器，无法运行此本地服务。

Codex CLI

codex mcp add cloudhpc --env CLOUDHPC_APIKEY=your-api-key -- cloudhpc-mcp

或编辑 ~/.codex/config.toml：

[mcp_servers.cloudhpc]
command = "cloudhpc-mcp"
tool_timeout_sec = 1900        # wait_for_simulation can wait up to 30 minutes

[mcp_servers.cloudhpc.env]
CLOUDHPC_APIKEY = "your-api-key"

使用 codex mcp list 检查。

Gemini

Gemini CLI

gemini mcp add -s user -e CLOUDHPC_APIKEY=your-api-key cloudhpc cloudhpc-mcp

或编辑 ~/.gemini/settings.json：

{
  "mcpServers": {
    "cloudhpc": {
      "command": "cloudhpc-mcp",
      "env": { "CLOUDHPC_APIKEY": "$CLOUDHPC_APIKEY" },
      "timeout": 1900000
    }
  }
}

$CLOUDHPC_APIKEY 会从你的 Shell 中读取密钥（export CLOUDHPC_APIKEY=...）；timeout（毫秒）允许 wait_for_simulation 最多等待 30 分钟。在 Gemini CLI 中输入 /mcp 检查。

Gemini 桌面应用和 Web 应用不支持自定义 MCP 服务。

GitHub Copilot

VS Code（Copilot Agent 模式）

在命令面板中运行 MCP: Open User Configuration（或在项目中创建 .vscode/mcp.json），并添加：

{
  "inputs": [
    { "type": "promptString", "id": "cloudhpc-key",
      "description": "cloudHPC API key", "password": true }
  ],
  "servers": {
    "cloudhpc": {
      "type": "stdio",
      "command": "cloudhpc-mcp",
      "env": { "CLOUDHPC_APIKEY": "${input:cloudhpc-key}" }
    }
  }
}

VS Code 会提示你输入一次密钥，并将其安全存储。在 Agent 模式下打开 Copilot Chat，并从工具选择器中启用 cloudHPC 工具。

Copilot CLI

编辑 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "cloudhpc": {
      "type": "local",
      "command": "cloudhpc-mcp",
      "args": [],
      "env": { "CLOUDHPC_APIKEY": "your-api-key" },
      "tools": ["*"]
    }
  }
}

或在 Copilot CLI 会话中使用 /mcp add。Windows 版 Microsoft Copilot 应用不支持自定义 MCP 服务。

其他 MCP 客户端

将 stdio 服务配置为使用命令 cloudhpc-mcp 和环境变量 CLOUDHPC_APIKEY。

Web 应用（托管端点）

端点：https://mcp.cloudhpc.cloud/mcp（可流式传输的 HTTP）。有两种身份验证方式：

• 使用 OAuth 登录（ChatGPT、Gemini、claude.ai 以及任何支持 MCP 服务 OAuth 的客户端）：参见使用 OAuth 登录。
• API 密钥请求头：客户端会在每次请求中通过 X-API-Key 请求头（或 Authorization: Bearer <key>）发送你的密钥。此端点不会存储任何内容：密钥只会在该请求中转发给 cloudHPC API。

与本地安装相比的变化：

• 不提供 inspect_case、upload_folder 和 download_results：托管服务无法访问你的计算机。
• 要上传案例，请压缩案例文件夹的内容（文件位于压缩包根目录），并向助手索取上传链接（get_upload_link）：它会提供一条可直接使用的 curl 命令。或者也可以通过 cloudHPC Web 应用上传。
• 要获取结果，请索取下载链接（get_download_link）。

使用 OAuth 登录

使用 OAuth 添加连接器时，助手会打开 cloudHPC 登录页面：

1. 检查请求访问权限的应用名称。它将能够查看你的模拟和存储、上传文件，以及启动或停止模拟；这些操作会计入你的账户费用。
2. 粘贴你的 API 密钥（如何查找 API 密钥）。
3. 可选：勾选只读访问：这样助手可以查看模拟、存储和结果，但不能启动、停止、恢复模拟、上传或删除文件，也不能打开远程桌面。适合安全地试用连接器，也适合只需查看运行情况的同事。
4. 点击连接。

助手永远不会看到密钥：它会收到一小时后过期的令牌，令牌会自动续期 30 天，之后你需要重新登录。若要撤销所有已连接助手的访问权限，请在 cloudHPC 个人资料中重新生成 API 密钥：访问权限会在一小时内失效。

claude.ai

对于支持自定义连接器的套餐：Settings > Connectors > Add custom connector，URL 为 https://mcp.cloudhpc.cloud/mcp，然后选择以下任一方式：

• 保持使用 OAuth 进行身份验证，并在提示时登录（使用 OAuth 登录），或
• 选择无需登录，并在请求标头下添加 X-API-Key = your-api-key。

在对话中通过工具菜单启用连接器。同一连接器也可用于 Claude 桌面应用和移动应用。

ChatGPT 网页版

在 ChatGPT 中开启开发者模式并添加自定义连接器（应用）：

• URL：https://mcp.cloudhpc.cloud/mcp
• 身份验证：OAuth

然后在 cloudHPC 页面上登录（使用 OAuth 登录）。

Gemini 网页版

在 Gemini 应用（gemini.google.com）中：

1. 点击左侧边栏中的自定义。
2. 打开连接器选项卡。
3. 点击**+ 自定义**，输入 URL https://mcp.cloudhpc.cloud/mcp，然后点击下一步。
4. 在打开的 cloudHPC 页面上登录（使用 OAuth 登录）。

Gemini 会自动完成注册：你无需提供 OAuth 客户端 ID 或密钥。连接器随后会显示在已连接的应用下。

Copilot 网页版

Microsoft Copilot 和 github.com 上的 Copilot Chat 不支持自定义 MCP 服务。

使用托管端点的其他客户端

任何支持带自定义请求头的可流式传输 HTTP 的 MCP 客户端均可使用，例如：

claude mcp add --transport http cloudhpc https://mcp.cloudhpc.cloud/mcp \
  --header "X-API-Key: your-api-key"

{ "mcpServers": { "cloudhpc": {
    "httpUrl": "https://mcp.cloudhpc.cloud/mcp",
    "headers": { "X-API-Key": "your-api-key" } } } }

（第二种是 Gemini CLI 格式；VS Code 使用 "type": "http"、"url" 和 "headers"；Codex CLI 在 config.toml 中使用 url 和 http_headers。）

重要须知

• 上传布局：案例文件夹中的内容会被打包到 upload.tar.gz 的根目录，并上传到一个与本地文件夹同名的存储文件夹。隐藏文件会被跳过。文件夹名称不得包含 , ( ) ' $ ~ " # 或空格。
• 资源：FDS、CalculiX 和 code_aster 在 highcpu 上启动；出现内存错误后，改用 standard，再改用 highmem。OpenFOAM 和其他仅使用 MPI 的求解器使用 highcore 或 hypercore。对于求解器，绝不会建议使用 highcpu 上的 1 vCPU，因为内存太少，无法启动。
• 检查运行：即使求解器失败，运行也可能以 COMPLETED 结束。运行结束时，服务端会扫描输出内容，查找错误指南中列出的错误并建议修复方法；下载后，还会检查求解器自身的日志（OpenFOAM log.*、FDS .out）。
• 费用按 vCPU 小时计费，并在运行结束时以欧元显示。
• 存储：文件会在创建 60 天后自动删除。请下载结果。
• 速率限制：免费账户每小时可调用 API 100 次，完整账户每小时可调用 500 次（无每日限制）。服务端会读取速率限制标头，并在超出限制前停止。
• 你的数据：工具返回的内容（模拟名称、日志、文件列表、费用）会发送给你所用助手的 AI 提供商，并受你自己的账户及其条款约束。对于机密项目，请检查提供商的数据设置（例如是否选择退出训练、商业计划）。使用本地安装时，你的 API 密钥会保留在你的计算机上；托管端点只会转发密钥，不会存储任何内容。使用 OAuth 登录时，助手只会持有经过加密且会过期的令牌，而不是密钥。

故障排除

问题	解决方法
助手看不到 cloudHPC 工具	编辑配置后重启应用；在终端应用中使用 /mcp 或 mcp list 检查。
command not found / 服务无法启动	使用 cloudhpc-mcp 的完整路径（which cloudhpc-mcp）。桌面应用不会加载 shell 的 PATH、conda 或虚拟环境。
Unauthorized: the API key is invalid	从 cloudHPC 个人资料页面重新复制密钥。
托管端点：Invalid header name	请按原样填写标头：X-API-Key: your-api-key（名称、冒号、空格、密钥）。
登录页面：“The API key was not accepted”	从个人资料中重新复制密钥（如何查找）；只粘贴密钥，不要包含空格。
助手要求提供 OAuth 客户端 ID 和密钥	移除连接器，然后使用 URL https://mcp.cloudhpc.cloud/mcp 重新添加：系统会自动注册，无需客户端 ID 或密钥。
助手要求你重新登录	30 天后或重新生成 API 密钥后出现这种情况属于正常；请使用当前密钥登录。
rate limit reached	等待下一个小时，或让助手降低检查频率。
等待运行的过程被中断	延长客户端的工具超时时间（参见上面的示例），或让助手分更短的步骤等待。

开发

git clone https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp
cd cloudhpc-mcp
pip install -e ".[test]"
pytest            # offline tests with a mocked API

服务模式（CLOUDHPC_MCP_MODE）：

模式	传输方式	用途
local（默认）	stdio	电脑上的桌面应用和终端应用
remote	streamable HTTP	托管端点；每个请求都会附带 API 密钥
remote + OAuth	streamable HTTP	设置 CLOUDHPC_OAUTH_SECRET（随机值；可使用逗号分隔的列表进行轮换）和 CLOUDHPC_PUBLIC_URL（公共基础 URL）：启用 OAuth 2.1 登录（PKCE、动态客户端注册和客户端 ID 元数据文档），用户可在服务页面粘贴 API 密钥；令牌会加密，不会存储任何内容。没有凭据的请求会收到带有 OAuth 挑战的 401；X-API-Key 仍可使用
public	streamable HTTP	无密钥的指南端点（例如供网站聊天机器人使用）：仅提供 solver_guide、list_solvers、list_machine_options、suggest_resources。使用 CLOUDHPC_CATALOG_APIKEY 中的密钥（专用且不含数据的账户）读取求解器和机器目录，并缓存 CLOUDHPC_CATALOG_TTL 秒（默认 3600）；每个客户端 IP 的请求数限制为 CLOUDHPC_PUBLIC_RATE_PER_MIN（默认 60）

scripts/e2e_test.py 会使用你的账户，通过真实 API 运行完整工作流：上传一个微型 FDS 案例，并在指定 --confirm-costs 后，使用 1 个 vCPU 运行约一分钟（--no-launch 仅上传；--cleanup 会在结束时删除测试文件夹）。

支持

• 文档：https://docs.cloudhpc.cloud
• 问题反馈：https://github.com/CFD-FEA-SERVICE/cloudhpc-mcp/issues

许可证

Apache-2.0