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.

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

Tool	Purpose
`klone_run(cmd, timeout=60, stdin=None)`	Run any shell command on klone. Returns stdout + (on success) stderr, capped at 1 MB per stream. Pipe large content via `stdin=`.
`klone_compute(name, cmd, salloc_args=..., timeout=120)`	Run `cmd` on a named, reusable salloc allocation. First call allocates; subsequent calls with the same name reuse the same node and share it via `srun --overlap`. Release with `klone_run("scancel -n <name>")` or let walltime expire.

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).