NSIP API Client and MCP Server: A Complete Guide

![NSIP API Client and MCP Server: A Complete Guide]({{ page.image }})

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

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

Overview

Part 1: Python Library

Installation

Quick Start

Core Methods

Error Handling

Command-Line Interface

Part 2: MCP Server

Installation

Configuration for Claude Desktop

Available Tools (15 Total)

Example Conversations

Part 3: The Shepherd Agent

Domains

Regional Awareness

Part 4: Resources & Resource Templates

URI Scheme

Available Resources

Part 5: Claude Marketplace Plugin

Installation

Available Slash Commands

Common Trait Abbreviations

Troubleshooting

Links