hmcpctl

hmcpctl

Manage IBM Power systems from your terminal or an AI assistant. hmcpctl connectsto the IBM Hardware Management Console (HMC) to inventory systems, inspect LPARsand VIOS partitions, manage resources, and run lifecycle operations.

Use it as a CLI, an MCP server, or a Python library.MCP access policies control which tools, connections, and targets an assistant can use.

Install

Requires Python ≥3.11 and uv.The project supports every stable, non-EOL CPython release at or above that floor.

Install the CLI and MCP server from source:

git clone https://github.com/randomparity/hmcpctl.git
cd hmcpctl
uv tool install --python 3.11 '.[app]'
hmcpctl --help

If your shell cannot find hmcpctl, run uv tool update-shell and open a newterminal. The app extra includes both the CLI and MCP server; for development,use the contributor setup.

The package is not published to an index. A project that depends on it as alibrary pins a release tag, whichnames the commit the release was verified at and carries theAPI compatibility contract. For the first release, v0.1.0:

dependencies = ["hmcpctl @ git+https://github.com/randomparity/[email protected]"]

Write hmcpctl[app] @ ... for the CLI and MCP server. With uv, uv add --raw "hmcpctl @ git+https://github.com/randomparity/[email protected]" writes that entry. Without--raw, uv moves the Git source into [tool.uv.sources], which stays out of your package'spublished metadata: other installers then look for hmcpctl on PyPI, where this projectpublishes nothing and has not reserved the name, so whoever registers it decides what installs.

Existing pre-release installations must use the one-timeclean-cutover procedure.

You need network access to an HMC and an HMC account with permissions for yourintended operations. The project targets HMC V8–V11; individual operations haveversion and firmware limits.Release 0.1.0 claims live verification for 15 system, LPAR, job and dedicated-PCIeoperations on HMC V10R3; thecompatibility pagelists them and shows how to check any other operation's state.

Configure

For one HMC, set the connection environment in your shell:

export HMC_HOST=hmc.example.com
export HMC_USER=admin
export HMC_VERIFY_SSL=true

Set HMC_PASSWORD through your shell or secret manager before running commands.Replace the example host and user with your own. TLS verification requires theHMC's CA certificate to be trusted locally. Verification is off by default ifHMC_VERIFY_SSL is omitted, which exposes credentials to interception.

Check the connection:

hmcpctl console info

This prints HMC information after a successful logon. Some operations also useSSH; see configurationfor SSH credentials, TOML profiles, friendly nicknames, and connection precedence.For multiple consoles, start with hmcpctl config init and edit the file it prints.

CLI quick start

Explore your systems and partitions:

hmcpctl systems list
hmcpctl systems health --json
hmcpctl lpars list --system <system-uuid>
hmcpctl lpars show <lpar-uuid>
hmcpctl vios list

Use UUIDs from the inventory output to identify resources. To change an LPAR,for example:

hmcpctl lpars modify <lpar-uuid> --mem 16384 --procs 2.0
hmcpctl lpars power-on <lpar-uuid>

Memory is in MiB; power-on asks for confirmation. HMC permissions and operationguards still apply. MCP access policies apply only to the MCP server; shellcommands run under your HMC credentials.

Use hmcpctl --help or hmcpctl lpars --help to explore.The CLI guidecovers storage, adapters, snapshots, provisioning, and job output.

MCP quick start

Create access-policy.toml in the platform's hmcpctl configuration directory:

• Linux: ~/.config/hmcpctl/ (or $XDG_CONFIG_HOME/hmcpctl/)
• macOS: ~/Library/Application Support/hmcpctl/
• Windows: %APPDATA%/hmcpctl/

Create the directory if needed. For an initial read-only server, add this policyto the file, preserving any policies already there:

[[policies.readonly.grants]]
effects = ["read"]
connections = ["<default>"]
targets = "all-targets"

This permits read tools across the default HMC. Read tools can also discloselocal profile and policy metadata; see thepolicy scope guide.

With the connection environment above available, start the server over stdio:

hmcpctl serve --access-policy readonly

An MCP client normally launches this process for you. For clients that use anmcpServers configuration, add:

{
  "mcpServers": {
    "hmc": {
      "command": "hmcpctl",
      "args": ["serve", "--access-policy", "readonly"],
      "env": {
        "HMC_HOST": "hmc.example.com",
        "HMC_USER": "admin",
        "HMC_PASSWORD": "<HMC-password>",
        "HMC_VERIFY_SSL": "true"
      }
    }
  }
}

Replace the placeholders and use your client's secret handling if available.If it cannot find the executable, use its absolute path from uv tool dir --bin.The client process must have access to the policy file and trusted HMC CA.

Try asking: “List my managed Power systems” or “Show fleet health.”Call hmc_effective_permissions to inspect the active policy.

An access policy is required. For broader permissions, migration from olderdeployments, audit logging, and HTTP setup, see theMCP server guide.HTTP is unauthenticated: keep it on loopback or put an authenticated proxy in front.

Documentation

• Documentation index — guides and reference.
• MCP tool reference — available tools, their effects, and one-line summaries.
• Environment variables — all connection and operation settings.
• Operation details — selectors, units, limits, and firmware-specific behavior.
• Development guide — stack, testing, source layout, and HMC API internals.

Contributing, security, and license

See Contributing for the development and pull-request path.Report suspected vulnerabilities through the private channel in theSecurity policy. This project is available under the License.