Ranch.Bot MCP Server

Ranch.Bot MCP Server

Work with cattle and sheep records from a local stdio MCP client. Requires Node.js 22 or newer,a Ranch.Bot account and access to a farm. Ranch.Bot does not operate a hosted MCP endpoint.

Release availability

Check the release and setup page for verified public versions.A source checkout or candidate is not evidence that a version is available on npm or in the Registry.The public CLI has separate setup instructions.For everyday records, use SMS and web setup.

Terminal commands

With the installed ranchbot-mcp command, run ranchbot-mcp login in a terminal and approve theURL and code in your browser. Configure your local MCP client to run ranchbot-mcp with no arguments.Use an absolute executable path if the client does not inherit your terminal PATH.ranchbot-mcp --help and ranchbot-mcp --version require no authentication.Run ranchbot-mcp logout to revoke the session before removing its local credentials.

Source development

Requires Node.js 22 or newer and an authorized Ranch.Bot development environment.

npm install
npm run build
npm test

Run the stdio entry directly from a local MCP client:

node /absolute/path/to/mcp-server/dist/index.js

Set these environment variables for the development environment:

The default is the stable public client ranchbot-mcp. Deploy its database migration beforeusing cloud authentication. A local API URL alone does not select installation-local accounts.

Development watch mode:

npm run dev

Local client configuration

A source checkout can point an MCP client at the built file. Example shape:

{
  "mcpServers": {
    "ranchbot-development": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "RANCHBOT_API_URL": "http://localhost:7001",
        "COGNITO_DEVICE_CLIENT_ID": "development-public-client-id"
      }
    }
  }
}

Use a real public OAuth client from the development environment. Never commit API keys, OAuthtokens, or secret-bearing client registrations.

Authentication

The stdio transport uses Ranch.Bot's OAuth device flow. Run node dist/index.js login in aterminal before connecting your MCP client. Visit the displayed URL and explicitly approve browseraccess. Tool calls without a session return terminal-login instructions and do not start login.node dist/index.js logout revokes the session before clearing the cache; failed revocation retainscredentials for a retry. --help and --version work without authentication. No arguments starts stdio.

Ordinary login requests read:farms, read/write animals, groups and records, and read:exports.Use list_my_farms then set_default_farm, or supply an explicit farm_id, before farm operations.A replacement session for a different principal clears the in-process farm selection. Tokens are cached locally in ~/.ranchbot-mcp-tokens.json with restricted filepermissions and refresh when the configured environment supports it.

The optional self-hosted HTTP transport uses bearer API-key auth for development compatibility. APIkeys are deprecated and are not part of customer onboarding.

Admin import sign-in

For internal concierge imports, add --admin to the stdio command (or to the local client'sargs array):

node /absolute/path/to/mcp-server/dist/index.js --admin

This selects the named ranchbot-admin-cli client and requests admin:imports alongside theeight ordinary scopes. It overrides COGNITO_DEVICE_CLIENT_ID; explicitly setting that variableto ranchbot-admin-cli also selects admin mode. The API must have that client registration, andan admin account must approve the displayed device code in the browser.

Admin sessions use ~/.ranchbot-mcp-admin-tokens.json and a separate persistent~/.ranchbot-mcp-admin-tokens.lock. Ordinary sessions retain their existing cache and lock.Run node dist/index.js login --admin before using admin mode;admin refresh and sign-in do not replace the ordinary session.

The list_pending_imports, get_import_request, and update_import_request_status tools requirethis admin session. Ordinary device sessions and the HTTP transport's API keys cannot use them.The API checks both the import capability and current admin status on every request.

Tool surface

The source server exposes farm-scoped tools for:

• farms and current farm context;
• animals and identifiers;
• groups;
• health, movement, feed, genetic, and other records;
• atomic birth events, linked follow-up tasks, and immutable farm protocol versions; and
• read-only Farm Memory.

External MCP writes execute through the MCP client's granted access. They do not use the Ranch.Botapp's review-before-saving screen. Ordinary CRUD tools call the farm endpoints and do not create theAction rows that back Change History today. The source guarantees to preserve are farm scope andrevocation.

preview_birth_event returns the complete birth bundle, resolved evidence, and a confirmation hashwithout saving farm data. Show every field to the producer and obtain explicit approval beforeconfirm_birth_event, preserving the exact request_id, bundle, and confirmation_hash.Corrections or changed evidence require a fresh preview and renewed approval. Confirmation requiresEDITOR access and write:records, write:animals, and write:groups scopes.list_birth_events and get_birth_event retrieve saved events; list_farm_tasks includes undatedTODOs, and update_farm_task changes status or the optional due date. list_protocol_versions andcreate_protocol_version use producer-provided immutable steps without inventing care instructions.

get_birth_source_evidence reads the source author's retained SMS media status and current-farmidentity candidates. It requires read:records, read:animals, and current farm access. Partial orambiguous matches require producer selection before birth confirmation.

Checks

npm run build
npm run typecheck
npm run lint
npm run prettier
npm test

Public setup returns only after current OAuth/scopes, npm and Registry read-back, and clean-machineinstallation, authentication, farm scope, representative reads/writes, revocation, and upgradespass. CLI 1.0.0 is already public and has independent setup guidance; local publication does not imply a hostedChatGPT/Gemini connection. Current status:ranch.bot/connect-your-ai.

License

MIT

Token-cache locking and upgrades

Token-cache reads and mutations use exclusive OS-managed locks (Node 22, pinned[email protected]). Lock files at ~/.ranchbot-mcp-tokens.lock persist after logoutand process exit; their existence does not mean a client holds the lock. The OS releasesownership when a client exits or crashes, allowing waiting clients to recover automatically.Do not delete or replace a lock file while clients are running.

Each tool call checks the shared cache so running clients adopt replacement sessions.Requests already using a revoked session may fail; failed requests are returned to the callerwithout automatic replay.

Stop all older CLI/MCP processes before upgrading. Concurrent old/new lock protocols areunsupported. A legacy file identifying a live process is rejected with an upgrade error;an abandoned legacy file is reused in place. Acquisition errors fail closed, and contentiontimes out after 30 seconds.

Caches are bound to the API origin and OAuth client ID. A mismatch is rejected without overwritingcredentials. Stop older clients before upgrading. For a cache without this metadata, run logout withits original RANCHBOT_API_URL and COGNITO_DEVICE_CLIENT_ID. Older provider credentials cannot berevoked by the device-session endpoint: revoke them with the original provider before removing thecache. A successful HTTP response alone does not establish legacy revocation.

Installation-local accounts retain the CLI-managed installation session: useranchbot login --local --api-url <installation> and set RANCHBOT_DEPLOYMENT_MODE=local plus thesame RANCHBOT_API_URL in the MCP client. MCP login/logout directs you to the CLI in that mode.