Quick start

1. Get a key

Create an account at my.roots.sh, then open Developers and create a key. Or do it from the terminal:

npm i -g https://docs.roots.sh/dl/roots-sh-0.1.0.tgz
roots signup

roots signup creates the account, saves a test key and a live key on this machine, and your sample farm is ready.

2. Read your farm

roots brief

curl https://api.roots.sh/v1/farms -H "Authorization: Bearer $ROOTS_API_KEY"

import { Roots } from '@roots-sh/sdk';
const roots = new Roots({ apiKey: process.env.ROOTS_API_KEY });
const brief = await roots.farms.brief();
console.log(brief.text);

3. Do something

Close the doors on the sample Roost:

roots roost doors.close doors=all

const [roost] = (await roots.roosts.list()).data;
await roots.roosts.command(roost.id, 'doors.close', { doors: 'all' });

4. Ask your farm

Connect the MCP server to Claude or any MCP client and ask “what needs me this morning?”

Errors

Errors come back as JSON with an HTTP status:

{ "error": { "code": "invalid_request", "message": "\"kg\" must be a number from 0.1 to 500." } }