tfgrid-mcp

An MCP server that lets Claude Code deploy virtual machines on the ThreeFold Grid.

The grid is ~440 machines in 36 countries with idle capacity going cheap. Getting one normally means ranking nodes yourself, guessing the price, and hand-rolling network and key arithmetic. This puts it behind a conversation.

What it does

• A VM. Pick size and country, see the node and the monthly price, approve, get an address.
• A public URL. Put an https:// gateway in front of a VM that is already running — no recreating it, no downtime.
• Your app. The agent sizes the machine from your project, clones the code onto it, and supervises the service. See docs/serving-an-app.md.

A VM can also take a public IPv4 instead, if you want it reachable with no overlay client.

How it works

Two steps, always in that order:

grid_plan_vm  →  ranks nodes, prices the VM, returns a plan_id   (costs nothing)
grid_apply    →  takes that plan_id and nothing else             (spends money)

The agent cannot deploy anything you have not seen and approved. Under the plan step it is grid-proxy for node data; under apply it is the ThreeFold grid-client SDK, which turns the approved plan into ZOS workloads. This server sits one level above that SDK — it decides where and what, the SDK does the deploying.

Your mnemonic lives in the OS keychain — never a config file, never a tool argument, never in a result, never in an error. Do not put it in the MCP client config as an environment variable: that file is world-readable and the agent reads it. TFGRID_MNEMONIC_DEV exists as a fallback for headless machines with no keychain, to be set by a process manager or a secrets injector.

Not everything needs a key. grid_account, grid_plan_vm and grid_list with a twin_id work with nothing stored at all — grid_account in particular never fails for want of a key, since it is the tool you call to find out why nothing else works. grid_plan_url and grid_inspect need an identity to sign a read of your own deployment. Only grid_apply needs a verified, funded account.

Install

A single static binary, no runtime services. Take one from Releases — Linux and macOS, amd64 and arm64:

tar -xzf tfgrid-mcp_*_linux_amd64.tar.gz
sudo install tfgrid-mcp /usr/local/bin/

Or with a Go toolchain, either of:

go install github.com/threefoldtech/tfgrid-mcp/cmd/tfgrid-mcp@latest
go build -o bin/tfgrid-mcp ./cmd/tfgrid-mcp          # from a clone

Then store your key and register the server:

tfgrid-mcp login  --network dev      # prompts, hidden input, stores in keychain
tfgrid-mcp status --network dev      # twin, KYC, balance — never the key

claude mcp add tfgrid -- /path/to/tfgrid-mcp serve --network dev --allow-write

Networks are dev, qa, test, main. Drop --allow-write for a read-only server: planning, listing and inspecting still work, nothing can create or cancel a contract.

Demo

you    : deploy me an ubuntu box, 4 cores 8 gigs, germany, under $20 a month

claude : node 3021, Frankfurt · 4 vCPU · 8 GB · 50 GB · $14.20/month
         alternatives: 4188 ($16.90), 2205 ($18.40)

you    : go

claude : ready · ssh root@5a4:be21:c19f:0e33:ff0f:6b18:921f:8031

Tools

Tool	Does
grid_account	twin, KYC, balance, and what is blocking a deploy — call it when nothing works
grid_plan_vm	size, place and price a VM; returns a plan_id
grid_plan_url	give a running VM a public URL; returns a plan_id
grid_apply	deploy an approved plan, by plan_id only
grid_list	what is running, gathered per deployment with every contract it holds; what the chain billed; what is in grace period
grid_inspect	per-workload state, addresses, and why anything failed
grid_cancel_contracts	cancel contracts by explicit ID; destroys the disk, permanently

Two resources carry the rules a model cannot infer: grid://guide (naming, reachability, timing) and grid://serve (running your own code behind a URL).

Developing

go test ./...
python3 evals/harness.py --network dev --binary ./bin/tfgrid-mcp

evals/harness.py is a property check: it drives the server over stdio JSON-RPC and asserts responses stay small and failures stay actionable. The eval proper is evals/tasks.md — plain-English requests scored by hand in a real Claude Code session.

.github/workflows/release.yml fires on a v* tag: tests, then a static binary per platform attached to a GitHub release. CGO_ENABLED=0 throughout, so everything cross-compiles from the Ubuntu runner — go-keyring reaches D-Bus in pure Go on Linux and shells out to security on macOS.

git tag v0.1.0 && git push origin v0.1.0

The server is stdio-only and holds one identity from the local keychain, so it is meant to be run on your own machine. There is nothing to host, and a shared instance would mean holding other people's mnemonics.

CLAUDE.md is the design document: the invariants, and the grid behaviour that cost a deploy to learn.

More

• docs/serving-an-app.md — a real end-to-end run, and what it cost.

Go 1.25 · MCP Go SDK v1.7.0 · stdio