UCR Research Computing nrp-mcp GitHub
nrp-mcpAn MCP server for the NRP Nautilus cluster
MCP server/Nautilus/v1.1.2

Run your research on Nautilus by talking to your AI assistant.

nrp-mcp is a small MCP server that runs on your own computer. Point it at your Nautilus sign-in and it turns "here is my code, run it on a GPU" into a reviewed plan and a running job. It knows the NRP's rules, so you don't have to learn Kubernetes first.

Start here View on GitHub Release v1.1.2
CI status Setup on Linux, macOS, Windows CI status
your AI client + nrp
You
Run train.py in ~/proj/leafnet on a GPU.
Assistant
Plan: one Job using pytorch/pytorch, 1 standard GPU, 4 cores, 16 GiB, 24-hour limit. It installs requirements.txt and runs python train.py. A100s need a quota you don't have, so this asks for any free standard GPU. Run it?
You
Yes.
Assistant
Running on an RTX A4000... Finished in 41 minutes. Copy results/ back?
What it does

From "run this" to a running job

Each tool is named for what you want rather than for Kubernetes objects. Every result starts with a plain-language summary and, where useful, the kubectl equivalent so you learn as you go.

Runs locally, as you

It runs on your computer with your kubeconfig and the NRP's own sign-in. It never reads or stores your token, and nothing leaves your computer except the Kubernetes calls you approve.

Reviewed plans, two-step confirm

Planning creates nothing. You see the image, size, decisions and manifests first. Running and cleanup need a single-use token bound to the exact plan, valid for 10 minutes.

Knows the NRP rules

Non-sensitive data only, Jobs instead of sleep loops, limits within 20% of requests, quota-gated GPUs and more. A plan that breaks a rule is refused, with the reason and the fix.

Jobs, sweeps and Slurm scripts

"Run it 200 times with different seeds" becomes an Indexed Job. #SBATCH lines are translated, and a Slurm array script runs unchanged with its array variables set per task.

"Why did it fail?"

Plain-language diagnosis with a fix: out of memory, no free GPU, quota, image pull, crashes. Progress and logs with tail and grep.

Notebooks, data and web apps

Private Jupyter or VS Code sessions through port-forward, in-cluster dataset downloads to a shared volume, and lab tools on HTTPS, published only after your approval code and expiring after 14 days.

Laptop setup on Linux, macOS, Windows

nrp-mcp setup installs kubectl and kubelogin into your user folder (SHA256-checked, no admin rights) and signs you in. CI installs and checks them on every change on all three systems.

Works with your MCP client

Run nrp-mcp client <name> once for Claude Desktop, Claude Code, VS Code, Cursor, Gemini CLI, OpenCode or Hermes Agent.

The tools

Ten tools

Six are read-only. The rest change things only as listed: with a flag, your approval, or a confirm token.

ToolChanges things?What it does
nrp_guidenoWalks you through step by step: checks your computer, sign-in, namespace, saving results and your runs, and tells your assistant the next step and the question to ask you
nrp_setuponly with fix=trueLaptop readiness: kubectl (version vs the cluster), kubelogin, NRP config, sign-in; installs or updates them with your yes
nrp_statusnoIdentity, namespaces, GPU quotas, workloads and what they ask for, volumes, public URLs, warnings
nrp_plannoInspects a project and a goal (job, sweep, web, session, llm-batch, volume, pull), applies every rule, returns a summary, decisions, refusals, the files it will copy and skip, and either a confirm token or needs_person_approval
nrp_runyes, after you approveRuns an approved plan: risky plans (web, GPU) after the person approves (question or code), low-risk plans with a token; writes a private run card to <project>/.nrp/runs/
nrp_watchnoProgress, logs (tail/grep), diagnosis with a fix, public URL check
nrp_cleanupyes, two stepsLists your runs, then deletes one after a second confirm
nrp_sessionnoReadiness, port-forward command and local link for a notebook or VS Code session
nrp_datauploads onlyList, upload small non-sensitive files, download results from a volume, or a job's saved results with down run=<id>
nrp_buildnoSuggests a Dockerfile and a GitHub Actions workflow that builds it into ghcr.io (or, with target=gitlab, an NRP GitLab kaniko file); explains public vs private images

Also served: resources nrp://policy, nrp://gpus, nrp://storage, nrp://llm, nrp://kb, and prompts first_run, port_slurm_script, parameter_sweep, my_job_failed, host_web_tool, teach_workshop.

How it works

One binary between your assistant and the cluster

Your AI client starts nrp-mcp serve and talks to it over stdio. Planning and rule checks are pure, tested code; only the kube step touches the cluster, using kubectl as you.

nrp-mcp architecture: the researcher's laptop runs the AI assistant and nrp-mcp, which plans, checks the NRP rules, gets the person's approval and runs kubectl as them against Nautilus; job results go to their own S3 bucket.
The whole picture: what runs on your laptop, what nrp-mcp creates on Nautilus, where results go, and a typical run from ask to cleanup. Click to open full size.

Small projects are copied into the pod as a ConfigMap and their requirements installed at start. Bigger ones get an image: nrp_build writes a GitHub Actions workflow, GitHub builds the image on every push into its container registry (ghcr.io), and nrp_plan image=... deploys it as built. A private image needs pull_secret= (a read-only token stored once in your namespace); a public one needs nothing. The full design, every rule and the test record are in SPEC.md.

Quick start

Five steps

Read the full one-page guide at docs/START-HERE.md. You need a Nautilus account and a namespace: sign in once at nrp.ai with your institution; students are added to a namespace by their PI at nrp.ai/namespaces, and faculty can request one. UCR researchers: see Getting access.

  1. Install nrp-mcp

    Linux or macOS:

    curl -fsSL https://raw.githubusercontent.com/UCR-Research-Computing/nrp-mcp/main/scripts/install.sh | sh

    Windows (PowerShell):

    irm https://raw.githubusercontent.com/UCR-Research-Computing/nrp-mcp/main/scripts/install.ps1 | iex

    Or download the archive for your OS from Releases, or with Go installed:

    go install github.com/UCR-Research-Computing/nrp-mcp/cmd/nrp-mcp@latest

  2. Download your NRP config

    At nrp.ai/config (it lands in Downloads).

  3. Get your computer ready (and optional S3 results)

    nrp-mcp setup
nrp-mcp s3 setup   # once: keys from https://nrp.ai/s3token/ (batch jobs need it to keep results)

    setup checks everything first and asks before changing anything. Then it installs kubectl and the kubelogin sign-in plugin (official releases, SHA256-checked, into your user folder, no admin rights), puts the NRP config in ~/.kube/config (backing up an existing one), and signs you in through your browser. Check readiness at any time with nrp-mcp doctor.

  4. Add it to your AI client

    Run nrp-mcp client <name> once in your terminal (writes user-scope config with the full binary path and keeps a .bak backup):

    nrp-mcp client claude-desktop   # or: claude-code, vscode, cursor, gemini, opencode, hermes
    ClientAutomatic (nrp-mcp client)
    Hermes Agentnrp-mcp client hermes (~/.hermes/config.yaml)
    Gemini CLInrp-mcp client gemini (~/.gemini/settings.json)
    OpenCodenrp-mcp client opencode (~/.config/opencode/opencode.json)
    Claude Codenrp-mcp client claude-code (~/.claude.json)
    Claude Desktopnrp-mcp client claude-desktop
    Cursornrp-mcp client cursor (~/.cursor/mcp.json)
    VS Codenrp-mcp client vscode (User/mcp.json, uses "servers")

    Pass --namespace <your-namespace> to pin a default namespace, then restart your AI client.

  5. Ask

    "Where do I stand on Nautilus?"

Limits

  • Code is copied as text files under 200 KB each (900 KB total). Bigger projects need an image (nrp_build) or git.
  • nrp_build suggests files; it doesn't build. Builds run on GitHub Actions (or NRP GitLab).
  • Job results written to results/ (or new files in /work) are saved to your personal NRP S3 bucket once you run nrp-mcp s3 setup with keys from nrp.ai/s3token.
  • Sessions are port-forwarded (nrp-mcp kubectl ... port-forward) and never public. For zero install, the NRP runs a hosted JupyterHub.
  • The browser sign-in step of setup can't run in CI and is tested by hand.
Research examples

20 fields, 20 worked examples

Each shows a realistic conversation with an AI assistant, what nrp-mcp builds, a compute estimate, honest limits, and a starter kit you can adapt. These are illustrations, not case studies: none of these groups use nrp-mcp today, none of these runs happened, and times and costs are stated assumptions. Read the index.

01Bee repellent screeningChemical ecology, ML 02Atmospheric rivers in CMIP6Climate dynamics 03Sea-ice floe sweepGranular physics 04Plant genome scansPlant genomics 05Mission records with an LLMHistory, digital humanities 06Exoplanet and Enceladus spectraAstrobiology 07Avian flu proteomicsVirology, proteomics 08Video model trainingComputer vision 09LLM confidence probingTrustworthy AI 10Cloud droplet parcel sweepsAtmospheric chemistry 11Joint-model simulation studyStatistics 12Wolbachia genomicsEntomology 13Open neuroimagingNeuroscience 14Air-quality dashboardAir quality 15Seismic waveformsSeismology 162D materials DFT scansCondensed matter 17Metabolomics matchingMetabolomics 18Course notebooksTeaching 19Econometrics Monte CarloEconometrics 20Open-text LLM codingSocial science

Runnable sample projects live in examples/: leaf-area-explorer (a web app) and slurm-array-bootstrap (an R bootstrap with a --array=0-9 Slurm script).