Ranch.Bot MCP server

Ranch.Bot MCP Server

Read and write cattle and sheep records through a local MCP server on your own computer. It uses your Ranch.Bot account over the stdio transport and exposes one farm at a time. Hosted connections are not public yet. ChatGPT access is a private pilot. Ranch.Bot’s Claude connector is in review; you can still connect it privately as a custom connector.

Requirements: Node.js 22 or newer, a Ranch.Bot account, and access to a farm.

Install and sign in

These commands install this source package's version (0.2.0). For the recommended public release, use the pinned command on MCP setup, the source of truth for setup; release status and promotion rules live in MAINTAINING.md. Stop older CLI and MCP processes before upgrading; never remove their active lock files.

npm install -g @ranchbot/mcp-server@0.2.0
ranchbot-mcp --version
ranchbot-mcp login

Open the printed URL, sign in, and explicitly approve the displayed code and requested access in your browser. No API key is needed. If login expires, run ranchbot-mcp login again; sign out with ranchbot-mcp logout. See Troubleshooting for access-denied and session problems, and keep passwords and token files out of assistant messages.

Configure a local stdio client

Point an MCP client at the installed command with no arguments:

{
  "mcpServers": {
    "ranchbot": { "command": "ranchbot-mcp", "args": [] }
  }
}

If the client cannot find the command, use its absolute executable path. Restart the client after changing configuration. ranchbot-mcp --help and ranchbot-mcp --version work without authentication. Any MCP client that can run a local stdio server works; this is not a certification of any named client.

First successful read

Ask the client to call these tools in order:

1. list_my_farms with {}. Choose the intended farm ID. If more than one farm is plausible and the producer did not name one, ask instead of guessing.
2. list_animals with {"farm_id":"<farm_id>"}, replacing the placeholder with that ID.

An empty list is a successful read. Pass farm_id explicitly on every scoped call; setting a default with set_default_farm is optional. If access is denied, check the account and farm membership; missing authentication means terminal login, then retry. Tool calls never start browser approval. A different account clears the process's default farm.

list_animals accepts query, match_mode (exact default, or partial) and identifier_type; exact matches saved identifiers and the current profile name, partial is literal substring discovery over profile names and NAME/MANAGEMENT_TAG identifiers. list_records accepts animal_id, group_id, include_group_context and explicit inclusive/exclusive applied_from/applied_before RFC3339 bounds; the first three and the bounds activate bounded history mode. Scoped credentials need the matching extra read scope for a target filter.

A useful read-only task: "Summarize the selected farm's current inventory." Read the complete relevant population, follow each operation's pagination (skip/take) and returned total, and report incomplete retrieval rather than presenting a first page as the whole answer.

Writing farm data

Ordinary writes save directly under your server permissions, without the app confirmation screen or its Change History. Before any mutation, present the operation, farm, resolved targets, exact values, and consequences and get explicit approval. Read the result back afterwards. If the outcome is uncertain, reconcile with reads before proposing another write.

Roles and scopes both apply: Readers can read, including the safe lookup_animal_by_eid; Editors or Owners can create and update and confirm a birth; deleting animals, groups, records, or identifiers needs Owner access. Birth confirmation also needs the write:records, write:animals, and write:groups scopes. A missing scope and a missing role are separate problems.

Direct births use preview_birth_event → approval → confirm_birth_event. Saved amendments and entered-in-error use preview_workflow with operation: "amend_birth", the record revision and a reason, then exact approval and commit_workflow, when exposed by the connected release. Never re-record a birth as a correction; if capability is missing, stop and contact support. Read the birth events reference before handling births.

Farms can configure a versioned record_birth template that drives the shared preview_workflow → approval → commit_workflow flow. The list_workflow_templates, get_workflow_template, create_workflow_template, publish_workflow_template_version, update_workflow_template_state, and set_default_workflow_template tools manage that configuration (Owner writes with write:farms). After upgrading from a login that lacks write:farms, run ranchbot-mcp login and approve a fresh authorization. Refresh preserves the existing grant; it cannot add scopes. A new grant does not elevate your farm role. Commit requires the exact preview_hash read back from a fresh preview; a stale hash is rejected. Templates change labels, visibility, defaults, and custom observations only — the meaning and review controls of core birth fields do not change. See the workflow guide for the run and configuration steps.

Agent skill

The package ships the public Agent Skill bundle at skills/ranchbot (SKILL.md plus references/). It is optional guidance, not a capability or a security boundary; installation details are in the MCP reference.

Task references

• MCP reference — connection, tool discovery, farm context, errors, and optional skill installation.
• Birth events reference — preview, confirmation, retry, saved amendments, and capability limits.
• Exports reference — archive create, poll, cancel, and download.
• Mixed-source reconciliation — historical imports, coverage ledgers, and lender-document caveats.

Jobs for an external assistant

A producer can authorize a local assistant to reconcile years of lambing spreadsheets, iPhone notes, messages, and livestock PDFs against one farm, produce custom reports, or compare farm history with an authorized lender or AgriStability snapshot for the same population and date. Totals are aggregate evidence, not individual animals or proof of current group membership; this is livestock reconciliation, not financial advice. Follow the mixed-source reconciliation recipe and the workflow pagination rules; MCP does not persist the coverage ledger.

Package guides

• Workflows — find an animal, save an ordinary record, and preview and confirm a birth, with inputs, pagination, and recovery.
• Architecture — the request path and which component enforces each guarantee.
• Troubleshooting — login, farm selection, lock, and access problems.
• Development — credential-free checks, the authenticated development server, and packaging.
• Contributing — how changes reach this exported repository and where to send feedback.
• Security — how to report a vulnerability privately.

Maintainer instructions

See MAINTAINING.md for development, admin login, local installations, EID migration, authentication troubleshooting, and detailed credential-lock recovery. For shell commands, use CLI setup. For everyday record entry, use SMS and web setup. Support: support@ranch.bot.

License

MIT. See LICENSE.