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