NSIP API Client & MCP Server

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:

nsip-client — Python library for direct programmatic access to NSIP’s genetic evaluation database
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

Data Models

from nsip_api_client.models import AnimalDetails, Trait, SearchCriteria

# AnimalDetails contains:
# - lpn_id, name, breed, gender, date_of_birth
# - status, owner info
# - traits: dict of Trait objects with value, accuracy, units

# SearchCriteria for filtering:
criteria = SearchCriteria(
    breed="Suffolk",
    gender="Ram",
    min_birth_date="2023-01-01",
    trait_filters={"WWT": (10, None)}  # WWT >= 10
)

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”

Transport Options

# stdio (default for Claude Desktop)
nsip-mcp-server

# HTTP (web applications)
nsip-mcp-server --transport http --port 8080

# WebSocket (real-time apps)
nsip-mcp-server --transport websocket --port 8080

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

Expert Persona

The Shepherd follows professional communication principles:

Evidence-Based — Cites NSIP data and research
Uncertainty-Aware — Acknowledges limitations
Actionable — Provides concrete next steps
Safety-First — Recommends veterinary consultation when appropriate

Response Structure:

Direct Answer
Context (why this matters)
Recommendations (specific actions)
Considerations (trade-offs, alternatives)
Sources (data references)

Usage Examples

Breeding Consultation:

“I’m running 40 Katahdin ewes in Ohio. What traits should I prioritize when selecting a new ram?”

Health Guidance:

“What’s the parasite management calendar for Southeast sheep operations?”

Economic Analysis:

“Is it worth paying $3,000 for a ram with top 1% genetics for a small hobby flock?”

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

Returns heritability coefficients and genetic standard deviations for each trait.

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

Regional Data:

nsip://static/regions/northeast
nsip://static/regions/southeast
nsip://static/regions/midwest
nsip://static/regions/southwest
nsip://static/regions/mountain
nsip://static/regions/pacific

Includes climate data, common breeds, regional challenges, and management considerations.

Disease Guides:

nsip://static/diseases/{region}

Nutrition Guidelines:

nsip://static/nutrition/{life_stage}/{region}

Calendar Templates:

nsip://static/calendar/{month}/{production_type}

Combining Resources with Tools

Read resource: nsip://static/heritabilities/katahdin
Use tool: nsip_search(breed="Katahdin", trait_filters={"WWT": 15})
Use tool: shepherd_breeding(goal="maternal improvement")

Part 5: Prompts & Workflows

MCP Prompts provide pre-configured interaction patterns for structured analysis.

Skill Prompts (Single-Shot Analysis)

Prompt	Purpose
`ebv-analyzer`	Interpret EBVs for an animal
`flock-import`	Import flock data for analysis
`inbreeding-calculator`	Assess inbreeding risk between animals
`mating-plan`	Generate optimal mating combinations
`progeny-report`	Analyze offspring performance
`trait-improvement`	Strategy for improving specific traits
`ancestry-builder`	Build pedigree visualization
`flock-dashboard`	Overview of flock genetics
`selection-index`	Calculate custom selection index
`breeding-recommendations`	Tailored breeding strategy

Shepherd Consultation Prompts

/nsip:consult "What ram traits should I prioritize?"
/nsip:consult --domain breeding "Evaluate this ram for my flock"
/nsip:consult --domain health "Parasite management for summer"
/nsip:consult --domain calendar "Plan my breeding season"
/nsip:consult --domain economics "Is this ram worth the price?"

Guided Interview Prompts

For complex decisions, guided interviews walk through multi-step analysis:

Guided Mating Plan:

Flock assessment (ewes, goals, constraints)
Ram evaluation (available sires, EBVs)
Inbreeding check (pedigree analysis)
Mating assignments (optimized pairings)
Expected outcomes (genetic progress projection)

Trait Improvement Strategy:

Current state (flock averages)
Target identification (which traits to improve)
Selection pressure (how aggressive)
Timeline (generations to goal)
Implementation plan (culling/selection criteria)

Workflow Examples

Ram Purchase Evaluation:

/nsip:lookup {lpn_id}           # Get ram details
/nsip:lineage {lpn_id}          # Check pedigree
/nsip:progeny {lpn_id}          # Review offspring
/nsip:consult --domain economics "ROI for this purchase?"
/nsip:consult --domain breeding "Fit for my flock goals?"

Seasonal Breeding Planning:

/nsip:traits katahdin           # Get breed parameters
/nsip:consult --domain calendar "Breeding dates for March lambing"
/nsip:consult --domain health "Pre-breeding health protocol"
/nsip:consult --domain breeding "Selection criteria this year"

Part 6: 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:health`	Server health metrics
`/nsip:test-api`	Validate connectivity
`/nsip:consult`	Shepherd consultation

Plugin Configuration

The plugin reads configuration from environment or settings:

{
  "nsip": {
    "cache_ttl": 3600,
    "max_results": 100,
    "default_region": "midwest"
  }
}

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

Overview

Part 1: Python Library

Installation

Quick Start

Core Methods

Data Models

Error Handling

Command-Line Interface

Part 2: MCP Server

Installation

Configuration for Claude Desktop

Available Tools (15 Total)

Example Conversations

Transport Options

Part 3: The Shepherd Agent

Domains

Regional Awareness

Expert Persona

Usage Examples

Part 4: Resources & Resource Templates

URI Scheme

Available Resources

Combining Resources with Tools

Part 5: Prompts & Workflows

Skill Prompts (Single-Shot Analysis)

Shepherd Consultation Prompts

Guided Interview Prompts

Workflow Examples

Part 6: Claude Marketplace Plugin

Installation

Available Slash Commands

Plugin Configuration

Common Trait Abbreviations

Troubleshooting

Links