cloudhpc-mcp

# cloudHPC MCP server

Run engineering simulations on [cloudHPC](https://cloudhpc.cloud) from AI assistants
that support the Model Context Protocol (MCP): Claude, ChatGPT/Codex, Gemini,
GitHub Copilot and others, from their desktop apps, terminal apps and, where
supported, web apps. Inspect a local case, get vCPU/RAM advice, upload the
folder, launch, monitor, diagnose errors and download the results, all from a
conversation.

Supported solvers: everything available on cloudHPC (FDS, OpenFOAM,
snappyHexMesh, DAFoam, code_aster, CalculiX, OpenRadioss, SU2, openTELEMAC,
LIGGGHTS, OpenLB, EnergyPlus, CONTAM, ...). Resource advice
follows the [cloudHPC scalability rules](https://docs.cloudhpc.cloud/scalability/)
and run diagnosis follows the [cloudHPC errors guide](https://docs.cloudhpc.cloud/errors/).

- [What you can ask](#what-you-can-ask)
- [Safe first prompts](#safe-first-prompts)
- [Tools](#tools)
- [Installation](#installation)
- [Connect your AI assistant](#connect-your-ai-assistant)
  - [Claude](#claude) · [ChatGPT / Codex](#chatgpt--codex) · [Gemini](#gemini) · [GitHub Copilot](#github-copilot) · [Other clients](#other-mcp-clients)
  - [Web apps (hosted endpoint)](#web-apps-hosted-endpoint)
- [Good to know](#good-to-know)
- [Troubleshooting](#troubleshooting)

## What you can ask

- *"Check the FDS case in this folder and tell me which resources to use."*
- *"Run it on cloudHPC and download the results when it finishes."*
- *"What is the status of my running simulations?"*
- *"My last run failed: what went wrong?"*

## Safe first prompts

Start with questions that only read data, then move on to actions that cost
money once you are comfortable with how the assistant works:

1. *"How do I prepare an OpenFOAM case for cloudHPC?"* (no account needed)
2. *"List my last simulations and summarise their status."*
3. *"Why did my last simulation fail? Check the log."*
4. *"Which vCPU and RAM type should I use for an FDS model with 8 meshes and 2
   million cells?"*
5. *"What is in the storage folder of my last run, and which files are results?"*

Only then: *"Upload this case and launch it"*, *"Resume simulation 1234"*. Every
action that costs money or deletes data asks for your confirmation first, and
the assistant shows you what it will do. With OAuth sign-in you can also
connect with **read-only access** (see [Sign-in with OAuth](#sign-in-with-oauth)).

## Tools

| Tool | What it does |
|---|---|
| `inspect_case` ¹ | Detect solver and model size of a local folder (FDS meshes/MPI groups, OpenFOAM cells, CalculiX nodes, ...) and run pre-flight checks |
| `suggest_resources` | vCPU and RAM type recommendation, with reasoning |
| `solver_guide` | How to prepare a case for a solver: input files, what cloudHPC does automatically, restart, optional settings, parallelism, logs |
| `list_solvers`, `list_machine_options` | Available solvers, vCPU counts and RAM types |
| `upload_folder` ¹ | Compress a local case folder and upload it to your storage |
| `launch_simulation` | Launch a run (**asks for confirmation**) |
| `list_simulations`, `get_simulation`, `wait_for_simulation` | Follow your runs; finished runs include a diagnosis of known errors |
| `sync_simulation` | Upload partial results of a running job |
| `stop_simulation` | Soft or hard stop (**asks for confirmation**) |
| `resume_simulation` | Resume a stopped run with the same solver, vCPU, RAM type and folder (FDS and OpenFOAM; **asks for confirmation**) |
| `start_desktop` | Start a Linux or Windows remote desktop for post-processing; billed until you stop it (**asks for confirmation**) |
| `open_remote_desktop` | Browser remote-desktop link of a running job |
| `list_storage`, `list_results` | Browse your storage and result archives |
| `download_results` ¹ | Download result archives and extract them locally |
| `get_upload_link`, `get_download_link` | Temporary links to upload/download single files |
| `delete_storage` | Delete a file or folder (**asks for confirmation**) |
| `api_usage` | API rate limits and calls used |

Actions that cost money or delete data (launching a run, a hard stop,
deleting from storage) always need your confirmation. In apps that support it
(e.g. Claude Code) the server shows you a confirmation dialog directly, so the
assistant cannot confirm on your behalf; in other apps the assistant shows you
a summary and waits for your OK.

¹ Only with the local installation: they work on files on your computer. In web
apps (hosted endpoint) use `get_upload_link` / `get_download_link` instead.

## Installation

Requirements:

- Python 3.10 or newer
- A cloudHPC account and its API key: open your cloudHPC profile page
  ([APIKEY docs](https://docs.cloudhpc.cloud/APIKEY/)). The key gives full access
  to your account: keep it private.

Install with [pipx](https://pipx.pypa.io) (recommended: isolated, and the
command ends up in `~/.local/bin`, easy to find for desktop apps):

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

or with pip:

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

This installs the `cloudhpc-mcp` command. Find its full path, you may need it
below:

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

The API key is read from the `CLOUDHPC_APIKEY` environment variable or, if that
is not set, from the file `~/.cfscloudhpc/apikey` created by
[cloudHPCexec](https://github.com/CFD-FEA-SERVICE/CloudHPC/tree/master/exampleAPI).

## Connect your AI assistant

There are two ways to connect:

- **Local installation** (desktop and terminal apps): the server runs on your
  computer, so it can read your case folders and save results next to them. All
  tools are available. Recommended.
- **Hosted endpoint** (web apps): `https://mcp.cloudhpc.cloud/mcp`, nothing to
  install. You connect by signing in once with your API key (OAuth) or by
  sending the key in a header. It cannot read files on your computer: you
  upload cases and download results with temporary links (or from the cloudHPC
  web app). See [Web apps](#web-apps-hosted-endpoint).

| Assistant | Desktop app | Terminal (Linux) | Web app |
|---|---|---|---|
| Claude | [Claude Desktop](#claude-desktop) (Windows, macOS, Linux beta) | [Claude Code](#claude-code) | [claude.ai](#claudeai) (custom connector) |
| ChatGPT | [ChatGPT desktop app](#chatgpt-desktop-app) (where MCP servers are available) | [Codex CLI](#codex-cli) | [ChatGPT](#chatgpt-web) (OAuth sign-in) |
| Gemini | not supported: no Gemini desktop app with MCP support | [Gemini CLI](#gemini-cli) | [Gemini](#gemini-web) (OAuth sign-in) |
| GitHub Copilot | [VS Code (Copilot agent mode)](#vs-code-copilot-agent-mode) | [Copilot CLI](#copilot-cli) | not supported |

In every example replace `your-api-key` with your key. If the assistant cannot
find the `cloudhpc-mcp` command, write its full path instead (see
[Installation](#installation)).

### Claude

#### Claude Desktop

Open **Settings > Developer > Edit Config** and add the server to
`claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: use **Edit Config** to open the file

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

Restart Claude Desktop. The cloudHPC tools appear in the tools menu of a new
conversation.

#### Claude Code

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

`--scope user` makes it available in every folder. Check it with `claude mcp list`
or `/mcp` inside Claude Code.

### ChatGPT / Codex

#### ChatGPT desktop app

In recent versions of the ChatGPT desktop app: **Settings > MCP servers > Add
server**, choose **STDIO**:

- Command: `cloudhpc-mcp`
- Environment variable: `CLOUDHPC_APIKEY` = `your-api-key`

The app shares its MCP configuration with Codex (`~/.codex/config.toml`, see
below), so a server added in one is available in the other. Availability
depends on app version and plan. The ChatGPT **web** app only supports remote
connectors and cannot run this local server.

#### Codex CLI

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

or edit `~/.codex/config.toml`:

```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"
```

Check it with `codex mcp list`.

### Gemini

#### Gemini CLI

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

or edit `~/.gemini/settings.json`:

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

`$CLOUDHPC_APIKEY` takes the key from your shell (`export CLOUDHPC_APIKEY=...`);
`timeout` (milliseconds) lets `wait_for_simulation` wait up to 30 minutes.
Check it with `/mcp` inside Gemini CLI.

The Gemini desktop and web apps do not support custom MCP servers.

### GitHub Copilot

#### VS Code (Copilot agent mode)

Run **MCP: Open User Configuration** from the Command Palette (or create
`.vscode/mcp.json` in a project) and add:

```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 asks for the key once and stores it securely. Open Copilot Chat in
**Agent** mode and enable the cloudHPC tools from the tools picker.

#### Copilot CLI

Edit `~/.copilot/mcp-config.json`:

```json
{
  "mcpServers": {
    "cloudhpc": {
      "type": "local",
      "command": "cloudhpc-mcp",
      "