MCP Server

What RanchBot/mcp-server does

RanchBot/mcp-server MCP server gives a local MCP-compatible assistant access to cattle and sheep records stored in Ranch.Bot. The process runs on the user's computer and communicates with the client through the stdio transport; Ranch.Bot does not provide a hosted MCP endpoint for this package.

Access is scoped to one farm at a time. The account must have access to the selected farm, and the user's Ranch.Bot role and granted scopes determine which operations are available. Readers can retrieve data, while Editors and Owners can perform selected create and update operations. Deletion requires Owner access.

How it works

After installation, the ranchbot-mcp command starts the local server without command-line arguments. The user signs in through a browser using ranchbot-mcp login, approves the displayed code and requested access, and then configures an MCP client to launch the command. No API key is required. If the session expires, the login command can be run again; ranchbot-mcp logout signs out.

A typical first read calls list_my_farms, selects the intended farm ID, and then calls list_animals with that ID. Farm-scoped calls should pass farm_id explicitly, although set_default_farm can optionally establish a default. Paginated operations require following skip, take, and the returned total so that an assistant does not mistake the first page for the complete population.

Births use a separate preview-and-confirm process. The assistant previews the event, obtains explicit approval, and confirms it using the approved workflow. Ordinary writes are applied directly under the server user's permissions rather than through Ranch.Bot's application confirmation screen.

Setup and configuration

RanchBot/mcp-server MCP server requires Node.js 22 or newer, a Ranch.Bot account, and access to a farm. The source README shows installation with npm install -g @ranchbot/mcp-server@0.1.5, followed by ranchbot-mcp --version and ranchbot-mcp login. The linked Ranch.Bot MCP setup documentation is the stated source for the recommended public-release command.

A local client can use this configuration:

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

Use the executable's absolute path if the client cannot locate the command, then restart the client after changing its configuration. The package also includes an optional Agent Skill bundle under skills/ranchbot; it provides guidance and does not add capabilities or act as a security boundary.

Tools and capabilities

Documented capabilities include:

• Listing farms and animals, including the safe lookup_animal_by_eid operation.
• Creating and updating permitted farm records and livestock data.
• Deleting animals, groups, records, or identifiers when the account has Owner access.
• Previewing and confirming birth events.
• Listing, reading, creating, publishing, and changing the state of workflow templates, plus selecting a default template.
• Creating, polling, cancelling, and downloading exports.

Workflow-template commits require the exact preview_hash from a fresh preview. Templates can alter labels, visibility, defaults, and custom observations, but not the meaning or review controls of core birth fields.

Limitations and notes

The server is local and stdio-based; there is no hosted Ranch.Bot MCP endpoint. Tool calls do not initiate browser approval, so authentication problems must be resolved through the terminal login flow. A missing permission scope and an insufficient Ranch.Bot role are separate causes of access failure.

Before any mutation, an assistant should show the operation, farm, resolved targets, exact values, and consequences, then obtain explicit approval and read the result back. If a write's outcome is uncertain, reconcile it with reads before retrying. Confirmed births cannot be corrected through these tools; the README directs users to Ranch.Bot support instead.

The server exposes records for the selected farm but does not persist the coverage ledger used for mixed-source reconciliation. Aggregate totals from reconciled documents are not individual-animal proof or financial advice.