Uxarray Mcp Server

UXarray MCP Server

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, Cursor, or any MCP client) analyze unstructured climate meshes with UXarray — locally on your machine, or remotely on an HPC system you have access to.

┌─────────────┐  stdio  ┌──────────────┐                    ┌─────────────────┐
│  AI client  │ ◀─────▶ │ uxarray-mcp  │ ◀── Globus ──────▶ │  HPC endpoint   │
│  (Claude…)  │   pipe  │ (your laptop)│    Compute (opt)   │ (Slurm/PBS node)│
└─────────────┘         └──────────────┘                    └─────────────────┘

> What the AI can do. Open meshes and datasets, compute area / zonal mean > / vorticity / divergence, subset, remap, plot, and run multi-step workflows. > All as natural-language prompts.

> Local by default; HPC is opt-in. Everything runs on your machine unless > you configure a Globus Compute endpoint. > The remote option only becomes available once such an endpoint exists — > running one requires an account and allocation on that HPC system, though a > shared/service-account endpoint can let authorized users submit without their > own login.

> ⚠️ What the AI can access. Any file you (or your HPC account) can read. > Any compute the configured endpoint can submit. Outputs are written to your > disk. See [SECURITY.md](SECURITY.md) before connecting any remote endpoint.

---

Pick your path

You are most likely one of:

1. Local user — laptop only, no HPC. → [Local install](#local-install).
2. HPC user, endpoint already exists — someone at your lab gave you a

Globus Compute endpoint UUID. → [Local install](#local-install), then [docs/remote-hpc.md](docs/remote-hpc.md).

1. HPC user, your own personal endpoint — you have a Globus identity and

shell access to an HPC machine, and want to stand up an endpoint just for yourself. → [Local install](#local-install), then [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md#solo-personal-endpoint-quickstart).

1. Group / shared endpoint operator — you're standing one up for a team,

project, or lab. → [Local install](#local-install), then the full [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md) including service-account migration and the MEP allowlist.

---

Local install

Five steps. Each is one command unless noted.

Step 1 — Install the package

Pick one. uv is the easiest; pip works too.

# Recommended
uv tool install --python 3.12 uxarray-mcp

# Or from a fresh clone (developer path)
git clone https://github.com/UXARRAY/uxarray-mcp-server.git
cd uxarray-mcp-server && uv sync --python 3.12

> Why --python 3.12? The server uses Globus Compute to submit work to > HPC endpoints, and Globus Compute's serializer is fragile across Python > minor versions — a 3.13 submitter against a 3.12 endpoint worker raises > WorkerLost on non-trivial payloads. HPC sites broadly ship 3.12 conda > stacks today, so we pin the install to match. Tracking removal of this pin > at globus/globus-compute#2139. > uv downloads 3.12 automatically if your system doesn't have it.

Step 2 — Write a starter config

uxarray-mcp setup

Creates ~/.config/uxarray-mcp/config.yaml with sensible defaults. Local mode needs nothing more.

Step 3 — Connect your AI client

Claude Desktop

uxarray-mcp install-claude        # merges the mcpServers block into your config
# or
uxarray-mcp install-claude --print-only   # prints the JSON to paste manually

Restart Claude Desktop. The uxarray server should appear in Settings → Developer.

Claude Code

claude mcp add uxarray --transport stdio -- uxarray-mcp serve

Then /mcp in Claude Code; pick uxarray.

Cursor / other MCP clients

Add an MCP server entry pointing at uxarray-mcp serve over stdio. See your client's MCP docs.

Step 4 — Sanity check

uxarray-mcp doctor

Prints a JSON diagnostic report. With no endpoints configured it reports a passing local setup and skips the remote checks; the process exits 0 when passed is true.

Step 5 — Ask the AI to do something

In your client, try:

> "Open `` and plot the mesh."

That's it for local use.

---

Going beyond your laptop

If you have an HPC account at a national lab or university cluster with Globus Compute available:

| You want to … | Read this | |---|---| | Connect to an endpoint someone else set up | [docs/remote-hpc.md](docs/remote-hpc.md) | | Stand up your own endpoint | [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md) | | Understand the security model first | [SECURITY.md](SECURITY.md) |

Both paths assume you've finished local install above.

---

What the MCP exposes

Intent-shaped tools, not raw UXarray bindings:

• get_capabilities — what can I do with this mesh?
• analyze_dataset — deterministic first-look: inspect, validate, area, zonal mean, plots.
• run_analysis — one operation at a time (gradient, curl, subset, remap, …).
• plot_dataset — mesh, geographic, variable, or zonal-mean plots.
• diagnose_endpoint, probe_path_access — endpoint health + file readability.
• run_workflow, resume_workflow, get_status, get_result, manage_session —

persisted sessions and multi-step workflows.

Tools that can run remotely take use_remote: bool and optional endpoint: str. The dispatcher falls back to local if the endpoint is unhealthy.

Full schema: [docs/tools.md](docs/tools.md).

---

CLI reference

| Command | Purpose | |---|---| | uxarray-mcp serve | Run the MCP server (used by your AI client) | | uxarray-mcp setup | Write a starter config | | uxarray-mcp endpoints add NAME UUID | Register a Globus Compute endpoint | | uxarray-mcp endpoints list | Show configured endpoints | | uxarray-mcp doctor | Validate local + (optionally) remote setup | | uxarray-mcp install-claude | Merge or print the Claude Desktop config block |

---

Risks (read before relying on output)

AI agents can misread prompts, pick the wrong file, get units wrong (e.g., sphere-radius scaling on derivatives), or run long jobs on your HPC allocation. uxarray-mcp does not guarantee correctness of agent-driven analysis. You are responsible for:

• Verifying numerical results before publishing.
• Reviewing what files the agent opens.
• Monitoring HPC job submissions against your allocation.

For the security model (what the agent and the endpoint operator can access), see [SECURITY.md](SECURITY.md).

---

Development

uv sync --extra hpc --extra docs --dev
uv run pre-commit run --all-files
uv run pytest tests/ --ignore=tests/test_remote_agent.py
uv run sphinx-build -b html docs docs/_build/html

Release process: [docs/release.md](docs/release.md).

License

See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: UXARRAY
• Source: UXARRAY/uxarray-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.