MCP Server Setup Guide

Connect Ranch.Bot to your AI assistant in a few minutes. This guide walks you through Claude Desktop, Claude Code, and other MCP clients.

Model Context Protocol (MCP) is an open standard that lets AI assistants work with outside tools and data. Ranch.Bot's MCP server lets your assistant look up and manage your livestock records — animals, groups, identifiers, and records — in plain language.

Before you begin, make sure you have:

A Ranch.Bot account (sign up here)
At least one farm created
Node.js 22 or newer installed
An AI assistant that supports MCP

AI Assistant	Status	Setup
Claude Desktop	Supported	Easy (5 minutes)
Claude Code	Supported	One command
Any stdio MCP client	Supported	Moderate
ChatGPT and web assistants	Hosted connection in the works	—

Step 1: Install Claude Desktop

If you haven't already, download and install Claude Desktop from claude.ai.

Step 2: Add Ranch.Bot to your configuration

Open Claude Desktop
Go to Settings → Developer
Click "Edit Config"
Add the Ranch.Bot MCP server:

{
  "mcpServers": {
    "ranchbot": {
      "command": "npx",
      "args": ["-y", "@ranchbot/mcp-server"]
    }
  }
}

Save the file and restart Claude Desktop

Note: If you have other MCP servers configured, add the Ranch.Bot entry inside the existing mcpServers object.

Step 3: Sign in once

The first time a tool needs your records, the server starts a browser sign-in:

Your assistant shows a verification URL and an 8-character code
Open the URL, sign in to Ranch.Bot, and enter the code
Approve the authorization request

That's it. Tokens are stored on your machine with restricted permissions and refresh automatically. You won't repeat this unless you revoke access.

Step 4: Verify the connection

Ask Claude:

List all my farms

If Ranch.Bot is properly connected, Claude will list your farms. You're all set.

Run one command in your terminal:

claude mcp add ranchbot -- npx -y @ranchbot/mcp-server

The same one-time browser sign-in applies on first use.

Any client that can run a stdio MCP server works — point it at:

npx -y @ranchbot/mcp-server

The configuration file for Claude Desktop is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Once connected, you can use natural language to:

Manage Animals

Create a new cow named Bessie with EID 840123456789
Show me all my animals
Find cow 123
Update cow 456 with weight 650 kg

Track Health Records

Record that cows 123, 124, and 125 got their spring vaccines today
Cow 842 was treated for pink eye with 2ml Draxxin
Which cows are due for pregnancy checks this month?

Manage Groups

Create a group called "Bred Cows"
Add cows 123, 456, and 789 to the bred group
Move all first-calf heifers to the close-up pen

Query Your Herd

How many animals do I have?
Which cows have been treated in the last 30 days?
Show me all animals in the hospital pen
What's the average weight of my calves?

"Authentication required" Error

Problem: Your assistant says authentication is needed.

Solutions:

Complete the browser sign-in (the server prints a verification URL and code)
If you revoked access earlier, the next request starts a fresh sign-in

"Device code expired" Error

Problem: The sign-in code expired before you entered it (codes last 15 minutes).

Solutions:

Ask your assistant to try again — a new code is issued
Complete the browser sign-in promptly

"Farm ID is required" Error

Problem: Ranch.Bot doesn't know which farm to use.

Solutions:

Ask: "What farms do I have access to?"
Say: "Set Smith Ranch as my default farm"
Or name the farm in your request: "List animals in Smith Ranch"

Ranch.Bot Tools Not Showing in Claude

Problem: Claude doesn't show Ranch.Bot as an available tool.

Solutions:

Verify the config file is saved correctly and is valid JSON
Restart Claude Desktop completely (Quit and reopen)
Make sure npx is available (run npx --version in a terminal)

Connection Issues

Problem: Claude can't connect to Ranch.Bot.

Solutions:

Check your internet connection
Ensure the Ranch.Bot API is accessible (visit https://api.ranch.bot/health)

You grant access by signing in — nothing connects on its own
Access is scoped to your farms and every change lands in your Change History
Revoke access anytime in Settings → Connected Apps
Tokens are short-lived (1 hour) and refresh automatically
Tokens are stored on your machine at ~/.ranchbot-mcp-tokens.json with restricted permissions; deleting that file also disconnects the assistant

Need assistance?

Ready to get started? Create your Ranch.Bot account