farmbot-agent

Agent-native CLI and MCP server for FarmBot hardware control.

Control your FarmBot from the terminal or let AI agents manage your garden through the Model Context Protocol.

Install

npm install -g farmbot-agent

Quick Start (CLI)

# Authenticate
farmbot login --email you@example.com --password yourpassword

# Check status
farmbot status

# Move the gantry
farmbot move --x 100 --y 200 --z 0

# Go home
farmbot home

# Emergency stop
farmbot e-stop

# Unlock after e-stop
farmbot unlock

# Execute Lua on device
farmbot lua 'toast("Hello from the CLI!")'

All commands support --json for structured output and --timeout <ms> (default: 30s).

Quick Start (MCP Server)

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "farmbot": {
      "command": "npx",
      "args": ["-y", "farmbot-agent", "mcp"],
      "env": {
        "FARMBOT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Claude Code

claude mcp add farmbot -- npx -y farmbot-agent mcp

Environment Variable Auth

For MCP mode, set FARMBOT_TOKEN as an environment variable. Get your token:

curl -s -X POST https://my.farm.bot/api/tokens \
  -H "Content-Type: application/json" \
  -d '{"user":{"email":"you@example.com","password":"yourpassword"}}' \
  | jq -r '.token.encoded'

MCP Tools

Tool	Description
farmbot_status	Device status: position, state, firmware
farmbot_get_position	Current X, Y, Z position (lightweight)
farmbot_get_device_info	Device config and identification
farmbot_move	Move gantry to absolute or relative position
farmbot_home	Home one or all axes
farmbot_emergency_stop	Immediately halt all movement
farmbot_unlock	Unlock after emergency stop
farmbot_lua	Execute Lua code on the device

MCP Resources

URI	Description
farmbot://device/status	Current device state as JSON

CLI Commands

Command	Description
farmbot login	Authenticate and store token
farmbot logout	Remove stored token
farmbot status	Show device status
farmbot move	Move to position (--x, --y, --z, --speed, --relative)
farmbot home	Go home (--axis, --speed)
farmbot e-stop	Emergency stop
farmbot unlock	Unlock after e-stop
farmbot lua <code>	Execute Lua on device

How It Works

farmbot-agent
├── CLI (Commander)      → Human-friendly terminal commands
├── MCP Server (stdio)   → AI agent tool interface
└── Shared Services      → farmbot-js (MQTT) + FarmBot REST API

FarmBot communication uses MQTT over the farmbot npm package. Commands are sent as CeleryScript RPC requests and responses are matched by UUID. The JWT token contains MQTT broker credentials.

Safety

• Coordinate bounds validation on all movement commands
• Rate limiting: max 30 move commands per minute (prevents runaway agent loops)
• Emergency stop is always available with short timeout
• Structured errors with codes, retry hints, and recovery suggestions

Development

git clone https://github.com/kieranklaassen/farmbot-agent
cd farmbot-agent
npm install
npm run build
npm test

License

MIT