How do I search 150M natural-history museum specimen records (plants, animals, fossils) via iDigBio MCP?

@pipeworx/mcp-idigbio — natural-history museum specimen search via iDigBio API

Package: npm install @pipeworx/mcp-idigbio Transport: library-style (export { tools, callTool }) — import and call directly, no stdio server API: search.idigbio.org/v2 (REST/GET, keyless) Auth: none required Coverage: ~150M digitized specimen records from US natural-history museum collections (plants, animals, fossils). Records are normalized Darwin Core indexTerms.

Tools (3)

1. search_specimens {scientific_name?, genus?, family?, country?, state_province?, recorded_by?, limit?} — Search specimen records filtered by any combination of taxonomy and geography. At least one filter required. Returns total count + specimen array (default 10, max 25). Each specimen includes: UUID, full taxonomy (scientific name, genus, family, order, class, kingdom, phylum), location (country, state, county, locality, lat/lon), collection metadata (date, collector, institution, catalog number, basis of record).

1. get_specimen {uuid} — Retrieve a single specimen record by its iDigBio UUID. Returns full normalized record plus taxon_rank and phylum fields.

1. count_by_field {field, scientific_name?, genus?, family?, country?, top_count?} — Aggregate specimen counts grouped by a field (country, stateprovince, family, genus, institutioncode, basisofrecord). Optional taxonomy/geography filters to scope counts. Returns top N buckets (default 10, max 25).

Execution pattern

npm install @pipeworx/mcp-idigbio

const mod = await import("@pipeworx/mcp-idigbio/src/index.ts");
const { callTool } = mod.default;

// Search for mountain lion specimens
const r = await callTool("search_specimens", { scientific_name: "puma concolor", limit: 5 });
// r.total -> 2771, r.specimens[0].uuid -> "0746b188-..."

// Get full specimen record
const s = await callTool("get_specimen", { uuid: "0746b188-c390-4ab1-bd20-5489a9c6c33c" });
// s.scientific_name -> "puma concolor", s.state_province -> "texas"
// s.latitude -> 31.205, s.institution -> "utep", s.basis_of_record -> "preservedspecimen"

// Count felidae specimens by country
const c = await callTool("count_by_field", { field: "country", family: "felidae" });
// c.buckets -> [{value: "united states", count: 34002}, {value: "canada", count: 2869}, ...]

Requires node --experimental-strip-types for direct .ts execution.

Verified results (17 calls, 17/17 OK)

search_specimens (5 calls):

• Puma concolor: 2,771 total records with coords, dates, institutions
• Quercus genus: 336,303 specimens across US herbaria
• Felidae family + US: 34,002 specimens (mix of fossil + preserved)
• Orchidaceae + Florida: 13,648 specimens
• Nonexistent species: 0 results, graceful empty response

get_specimen (2 calls):

• Real UUID (Puma concolor from Texas): full record with lat/lon (31.205, -105.023), collector, institution (UTEP), date (2013-05-18), basisofrecord (preservedspecimen)
• Invalid UUID: 404 "specimen not found" — graceful

count_by_field (7 calls):

• Felidae by country: US 34,002 / Canada 2,869 / Peru 2,255
• Quercus by institution: IBUNAM 20,080 / BRIT 16,287
• US specimens by family: Asteraceae 2.73M / Poaceae 2.05M (massive collections)
• Tyrannosaurus by basisofrecord: 37 fossil / 32 preserved
• Orchidaceae by state: Florida 13,648 / California 11,717 / Pennsylvania 10,383

Error handling (3 calls):

• No filter -> error "provide at least one filter"
• Empty field -> error "provide a field to group by"
• recorded_by filter -> 400 from API (see gotcha below)

Latency: p50 ~300ms per call

Gotchas

1. `recorded_by` filter is BROKEN — the searchspecimens tool accepts a `recordedby param that maps to iDigBio's recordedby` index field, but the iDigBio API returns HTTP 400 "Terms not found in index for type records" when this filter is used. The field exists in specimen records (visible in results) but is NOT indexed for search queries. Us