Ranch 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 the URL 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 before using 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, OAuth tokens, or secret-bearing client registrations.

Authentication

The stdio transport uses Ranch.Bot's OAuth device flow. Run node dist/index.js login in a terminal before connecting your MCP client. Visit the displayed URL and explicitly approve browser access. 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 retains credentials 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 listmyfarms then setdefaultfarm, 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 file permissions and refresh when the configured environment supports it.

The optional self-hosted HTTP transport uses bearer API-key auth for development compatibility. API keys 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's args array):

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

Shortened. The full README is on GitHub.