A complete guide to using the National Sheep Improvement Program (NSIP) tools for genetic analysis, breeding decisions, and AI-powered livestock management.

Overview

The NSIP ecosystem provides two complementary packages:

  1. nsip-client: Python library for direct programmatic access to NSIP’s genetic evaluation database
  2. nsip-mcp-server: MCP server enabling Claude and other LLMs to query sheep genetics data and provide expert breeding guidance

Both packages connect to the same NSIP data source, offering access to Expected Breeding Values (EBVs), pedigrees, progeny records, and breed-specific genetic parameters for over 20 sheep breeds.

Part 1: Python Library

Installation

# From PyPI
pip install nsip-client

# From GitHub (latest)
pip install git+https://github.com/epicpast/nsip-api-client.git

Quick Start

from nsip_api_client import NSIPClient

# Create client (context manager for automatic cleanup)
async with NSIPClient() as client:
    # Get available breeds
    breeds = await client.get_available_breed_groups()

    # Search for animals
    results = await client.search_animals(
        breed="Katahdin",
        gender="Ram",
        min_birth_date="2022-01-01"
    )

    # Get detailed animal information by LPN ID
    animal = await client.get_animal_details("123456")

    # Get pedigree (3 generations)
    lineage = await client.get_lineage("123456", generations=3)

    # Get offspring
    progeny = await client.get_progeny("123456")

Core Methods

Method Description
get_available_breed_groups() List all NSIP-registered breeds
get_statuses_by_breed_group() Get status codes for a breed
search_animals(criteria) Search with filters (breed, gender, dates, traits)
get_animal_details(lpn_id) Complete profile for an animal
get_lineage(lpn_id, generations) Multi-generational pedigree tree
get_progeny(lpn_id) Offspring list with performance data
search_by_lpn(lpn_id) Convenience method for full animal profile

Error Handling

from nsip_api_client.exceptions import (
    NSIPError,           # Base exception
    NSIPAPIError,        # API returned an error
    NSIPNotFoundError,   # Animal not found
    NSIPConnectionError, # Network issues
    NSIPTimeoutError,    # Request timed out
    NSIPValidationError  # Invalid parameters
)

try:
    animal = await client.get_animal_details("invalid-id")
except NSIPNotFoundError:
    print("Animal not found in NSIP database")
except NSIPConnectionError:
    print("Could not connect to NSIP servers")

Command-Line Interface

# List available breeds
nsip-search breeds

# Search for top rams
nsip-search animals --breed Katahdin --gender Ram --limit 10

# Get animal by LPN
nsip-search lookup 123456

Part 2: MCP Server

The MCP (Model Context Protocol) server enables AI assistants like Claude to query NSIP data and provide expert breeding guidance through natural conversation.

Installation

# Run directly via uvx (no installation required)
uvx nsip-mcp-server

# Or install via pip
pip install nsip-mcp-server

Configuration for Claude Desktop

Mac (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nsip": {
      "command": "uvx",
      "args": ["nsip-mcp-server"]
    }
  }
}

Windows: Configuration file at %APPDATA%\Claude\claude_desktop_config.json

Available Tools (15 Total)

Database Tools:

Tool Description
nsip_discover List breeds, statuses, database info
nsip_test_api Validate API connectivity
nsip_health Server health metrics

Animal Tools:

Tool Description
nsip_search Search animals with filters
nsip_lookup Get details by LPN ID
nsip_lineage Pedigree tree (ancestry)
nsip_progeny Offspring list
nsip_profile Complete animal profile
nsip_traits Trait value ranges for a breed

Shepherd Tools:

Tool Description
shepherd_consult General breeding consultation
shepherd_breeding Genetic selection guidance
shepherd_health Health and nutrition advice
shepherd_calendar Seasonal management planning
shepherd_economics Production cost analysis

Example Conversations

Finding Rams:

“Find Katahdin rams born after 2023 with WWT above 15”

Breeding Analysis:

“Look up LPN 123456 and tell me if this ram would improve my flock’s maternal traits”

Pedigree Review:

“Show me the 4-generation pedigree for this animal and identify any inbreeding concerns”

Economic Planning:

“Calculate the ROI if I purchase this $2,500 ram for a 50-ewe flock”

Part 3: The Shepherd Agent

The Shepherd Agent is an AI-powered breeding advisor delivering expert guidance across four specialized domains.

Domains

1. Breeding & Genetics

  • EBV interpretation with breed-specific context
  • Selection strategy aligned with production goals
  • Inbreeding coefficient assessment
  • Multi-generation genetic progress projection

2. Health & Nutrition

  • Regional disease prevention guidance
  • Life-stage-specific nutrition recommendations
  • Parasite risk assessment by season and region
  • Vaccination scheduling

3. Calendar Management

  • Seasonal task scheduling by production type
  • Breeding date calculation from lambing targets
  • Regional market timing windows
  • Full-year operational calendar generation

4. Economics

  • Itemized production cost breakdown
  • Breakeven price analysis
  • Ram purchase ROI calculation
  • Flock profitability modeling
  • Marketing channel comparison

Regional Awareness

The Shepherd automatically detects your region (Northeast, Southeast, Midwest, Southwest, Mountain, Pacific) and tailors advice accordingly:

  • Climate-appropriate management practices
  • Regional disease prevalence
  • Local breed recommendations
  • Market timing for your area

Part 4: Resources & Resource Templates

MCP Resources provide read-only access to structured breeding data through URI patterns.

URI Scheme

nsip://static/{category}/{identifier}

Available Resources

Heritabilities: Trait variation by breed:

nsip://static/heritabilities/katahdin
nsip://static/heritabilities/dorper
nsip://static/heritabilities/suffolk

Selection Indexes: Pre-weighted trait combinations:

nsip://static/indexes/terminal    # Market lamb production
nsip://static/indexes/maternal    # Ewe productivity
nsip://static/indexes/range       # Extensive grazing
nsip://static/indexes/hair        # Hair sheep breeds
nsip://static/indexes/balanced    # General purpose

Trait Glossary:

nsip://static/traits/growth       # BWT, WWT, MWWT, PWWT
nsip://static/traits/carcass      # REA, FAT, IMF
nsip://static/traits/reproduction # NLW, NLB
nsip://static/traits/parasite     # FEC, FAMACHA
nsip://static/traits/wool         # GFW, FD

Part 5: Claude Marketplace Plugin

The NSIP tools are available as a Claude Code plugin through the zircote marketplace.

Installation

# In Claude Code
/plugin install nsip@zircote-claude-marketplace

Available Slash Commands

Command Description
/nsip:search Search for animals
/nsip:lookup Get animal by LPN ID
/nsip:lineage Pedigree tree
/nsip:progeny Offspring list
/nsip:profile Complete animal profile
/nsip:traits Trait ranges for breed
/nsip:discover Available breeds and statuses
/nsip:consult Shepherd consultation

Common Trait Abbreviations

Code Trait Description
BWT Birth Weight Direct effect on lamb survival
WWT Weaning Weight Growth to weaning (60-90 days)
MWWT Maternal Weaning Weight Dam’s milk/mothering contribution
PWWT Post-Weaning Weight Growth 90-180 days
NLW Number Lambs Weaned Ewe productivity
NLB Number Lambs Born Fertility
FEC Fecal Egg Count Parasite resistance
REA Ribeye Area Carcass muscling
FAT Fat Depth Carcass composition

Troubleshooting

Connection Issues:

  • Verify internet connectivity
  • Check NSIP servers: nsip-mcp-server --test
  • Review firewall settings

Animal Not Found:

  • Verify LPN ID format (numeric)
  • Check breed spelling
  • Confirm animal is in NSIP database

Slow Responses:

  • Enable caching (default 1-hour TTL)
  • Reduce query scope with filters
  • Check network latency