klone-mcp

A minimal MCP server for UW Hyak (klone). Exposes two tools — klone_run (any shell command) and klone_compute (run commands on a named, reusable compute allocation) — plus documentation resources covering klone's filesystem layout, SLURM conventions, and curated shell commands.

Agents already know how to use squeue, sacct, sbatch, du, etc., and they know bash (heredocs to write files, pipes, etc). This MCP doesn't wrap any of it. It just gives the agent a convenient way to run commands on klone and find out what klone-specific utilities exist.

The SSH host can be overridden via the KLONE_SSH_HOST env var (default: klone). Useful for alternate aliases, a test cluster, or parallel configs.

If you want pre-typed wrappers around SLURM (klone_squeue, klone_log, klone_submit, …) checkout the structured-tools branch.

Prerequisites

• Python 3.10+

• A working SSH alias klone on your machine. Add this block to ~/.ssh/config if you don't have it (replace YOUR_UWNETID):

  Host klone
      HostName klone.hyak.uw.edu
      User YOUR_UWNETID
      ControlMaster auto
      ControlPath ~/.ssh/cm-%r@%h:%p
      ControlPersist 10h
      ServerAliveInterval 60

  Then run ssh klone once, complete the Duo push, and leave the terminal open. The persistent connection means ssh klone <cmd> from any other terminal won't re-prompt for the next 10 hours. The MCP reuses this same connection.

Related MCP server: Developer Toolbox MCP

Install

cd ~/klone/klone-mcp
pip install -e .

Or with uv:

cd ~/klone/klone-mcp
uv venv && source .venv/bin/activate && uv pip install -e .

Verify it runs

ssh klone whoami        # must return your NetID — seed the SSH session first

Register with Claude Code

claude mcp add klone -- python -m klone_mcp.server

The -- is required because claude mcp add would otherwise try to parse -m as its own flag.

If you installed into a venv, point at that venv's Python:

claude mcp add klone -- /path/to/.venv/bin/python -m klone_mcp.server

Or edit ~/.claude/settings.json directly:

{
  "mcpServers": {
    "klone": {
      "command": "python",
      "args": ["-m", "klone_mcp.server"]
    }
  }
}

Use it

claude

Inside the session:

"Run klone_run with whoami."

Should return your NetID. If Duo expired, you'll get a structured re-auth prompt — open a terminal, do ssh klone, complete Duo, leave that terminal open, and ask the agent to retry.

Tools

Things like df, du, sinfo, hyakalloc, scontrol, squeue, sacct, sbatch are not separate tools — invoke them via klone_run. See the klone://docs/commands resource for a curated list. To write a file, use a heredoc or stdin=: klone_run("cat > /tmp/x", stdin=body).