HPC MCP

New user? Start here: If you already have Remote Desktop Commander (RDC) connected to your Linux account, follow the RDC-assisted setup guide. ChatGPT can help inspect the cluster, install HPC MCP, and run tests through RDC. You must configure private Platform/Tunnel credentials yourself. Once HPC MCP works in a new ChatGPT conversation, RDC can be disabled.

Without RDC: follow the manual ChatGPT + Secure MCP Tunnel setup and then the user-level service guide.

A per-user Model Context Protocol (MCP) server for Linux HPC clusters, designed to work with an outbound OpenAI Secure MCP Tunnel. The server runs under an ordinary Linux account; it does not require root privileges or inbound firewall ports.

The code in this repository is independent of any particular cluster, user account, ChatGPT account, or Tunnel credentials. It is a research prototype, not a hardened command sandbox.

Features

• Read-only by default: bounded file listing/reading/searching, Git status/diff, Slurm or PBS job inspection, and system information.

• Opt-in file creation, guarded file replacement, allowlisted command execution (including CMake/Make/MPI workflows), and managed background processes with approved environment overrides and exit-code tracking.

• Separately opt-in Slurm/PBS submission and cancellation, plus locally configured read-only site commands (e.g. point/quota).

• User-level persistence via systemd --user when Linger is enabled, or a cron watchdog when available.

• No root, setuid, shared daemon, or inbound MCP TCP server.

Security: Enabling commands grants the MCP integration capabilities of your Linux user. The executable allowlist is not a sandbox. For example, allowlisting Python permits arbitrary code execution. See Security model before enabling any write or command tools.

Related MCP server: chatgpt-sol-local-bridge

Requirements

• Linux and Python 3.11 or newer, with python3 -m venv available.

• Access to PyPI (or a suitably configured internal package index).

• git for Git tools, squeue for Slurm or PBS job inspection and optional scheduler submission.

• For a ChatGPT connection: the separately installed official tunnel-client, a private Tunnel and credentials, and an eligible ChatGPT workspace. Availability and billing depend on the provider/account.

• For persistent operation: either a user systemd manager with Linger=yes or an active crond supporting user crontabs. Follow the cluster site's policies.

Installation

git clone https://github.com/mfukudaQED/hpc-mcp.git
cd hpc-mcp
./install.sh

If the system python3 is older than Python 3.11, explicitly choose a suitable interpreter when creating the environment:

./install.sh --python /path/to/python3.11

An existing .venv is reused and must itself use Python 3.11 or newer. The installer will not silently replace an incompatible environment. See Updating an existing installation.

Installation creates .venv and, if absent, ~/.config/hpc-mcp/config.toml with mode 0600. It does not activate a Tunnel.

Copy and edit the local config to select your authorized filesystem roots (default ~/work). Start with read-only permissions. To connect ChatGPT, follow Tunnel setup and Service backends. Keep ~/.config/hpc-mcp/tunnel.env and the Tunnel profile outside the repository.

To inspect user-service availability and activate after provisioning your private credentials:

./install.sh --service-status
./install.sh --activate --backend=auto

Alternatively use --backend=systemd, --backend=cron, or --backend=none. The installer does not change logind Linger settings or start system daemons. A Linger=no environment may not preserve user processes across logout.

Connect ChatGPT and manage the service

First, prepare a private OpenAI Platform Tunnel, a restricted runtime API key with Tunnels Read + Use, and a custom MCP plugin in your ChatGPT workspace. Creating/managing the Tunnel requires Tunnels Read + Manage. Platform API authorization and ChatGPT workspace access are separate; a ChatGPT subscription alone is not a substitute for a Platform key. See the detailed ChatGPT + Platform + Tunnel setup walkthrough.

If you already use Remote Desktop Commander (RDC), ChatGPT can assist with inspecting the Linux environment, installing HPC MCP, and testing it through RDC. You must handle private credentials and platform/plugin account authorization yourself. After verifying HPC MCP from a new chat, you can disable RDC. See RDC-assisted setup.

From the checkout directory (cd ~/work/hpc-mcp), manage the Tunnel with one backend:

./install.sh --service-status
./install.sh --activate --backend=auto

Automatic selection prefers usable systemd --user with Linger=yes, then cron if available. A cron stop alone is temporary because the scheduled watchdog can restart the Tunnel; use ./install.sh --remove-cron to stop and remove the cron schedule. Use neither sudo nor system-wide systemctl. After changing enabled MCP tools, restart your backend, select "Update tools" (or "Refresh tools") in ChatGPT Plugins, and test in a new chat.

Configuration

See config/config.example.toml. The default policy denies all writes, commands and Slurm submissions. Editing the private config requires restarting the Tunnel and refreshing tools in ChatGPT.

For testing with command execution enabled, you can restrict [commands].allowlist to ["whoami"] and test execute_command(argv=["whoami"], cwd="<an-allowed-root>"). This is strictly opt-in. For compiler, build, and MPI tool setup, see Development commands. The optional list_allowed_commands tool reports approved executables available on the service PATH.

Optional MCP File Manager

MCP File Manager is a separately installed, opt-in MCP Apps browser and text editor. It uses the existing HPC MCP connection, authorized filesystem roots and Secure MCP Tunnel: no second server is needed. File browsing is read-only by default. Text editing requires BOTH [extensions.file_manager].enable_edit = true and [permissions].enable_writes = true (which also enables HPC MCP's core file-write tools).

The current File Manager UI v16 asks ChatGPT to prefer a fullscreen/tab display and starts with its File Explorer collapsed. The ChatGPT host ultimately chooses how to display the MCP App. See the File Manager setup and usage guide.

Already using HPC MCP? See Updating an existing installation for the exact git pull, ./install.sh, optional package installation, per-user service restart and ChatGPT Update tools steps. Your existing private config and Tunnel credentials are not overwritten by the installer.

Slurm, PBS and site-specific commands

HPC MCP supports Slurm and PBS/OpenPBS through scheduler adapters. Choose the backend independently on each cluster in its private configuration:

[scheduler]
type = "slurm"   # or "pbs", "none"
# bin_dir = "/path/to/scheduler/bin"

[permissions]
enable_scheduler_submit = false
enable_scheduler_cancel = false
enable_site_tools = false

The scheduler-neutral tools are scheduler_list_jobs and scheduler_job_detail. Submitting an existing, reviewed script with scheduler_submit_script requires enable_commands = true and enable_scheduler_submit = true. Cancellation is separately opt-in. Legacy Slurm-only slurm_list_jobs and submit_slurm_script tools remain available on Slurm installations.

Site commands: each account can define trusted, fixed-argument [site_tools.NAME] entries in its private TOML file. For example, a local point enquiry can appear as site_point_balance(). No separate MCP instance is required for simple status commands.

No scheduler node-count cap is hard-coded in HPC MCP. Job resources are specified in each reviewed script and enforced by site policy. This project is not an OS sandbox.

See Scheduler adapters and site-specific tools for examples, security constraints, and migration from Slurm-only settings.

Development and tests

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q

The tests use mocks for systemd, cron, and Slurm-related behavior; passing tests alone does not establish service persistence across logout or correct behavior on another cluster.

Documentation

• Release history

• Site-specific examples (sham and ohtaka)

• HPC MCP 運用手順（日本語）：コマンド許可と Tunnel API キー更新

• Tunnel setup

• Scheduler adapters and site-specific tools

• Development, build, and MPI command workflows

• sham Intel oneAPI / Intel MPI service setup

• systemd and cron

• Security and limitations

• Architecture (Japanese)

• Contributing

Status

Version 0.3.0 is a research prototype. MCP tool discovery, direct stdio execution and a private Tunnel deployment have been tested on one HPC system; live PBS compatibility, broad portability, the cron backend on a real Linger=no host, and independent multi-user deployments are not yet verified.

This repository distributes source code; it does not publish a public ChatGPT plugin, nor does it contain or grant Tunnel access. HPC MCP is an independent community project and is not an official OpenAI product.

Licensed under the MIT License.