io.github.cyanheads/gbif-biodiversity-mcp-server

Resolve up to 50 scientific names to GBIF backbone taxon keys in one call — the batch counterpart to gbif_match_species for checklist, inventory, and species-list workflows that would otherwise need one round trip per name. Each name is matched independently and results are returned in input order, one entry per processed name. By default, an oversized batch processes the first 50 and returns the remainder in unprocessedNames. A name GBIF matched at a higher rank yields matchType HIGHERRANK with a note naming the taxon matched and what its taxonKey covers: that whole taxon, or its accepted taxon when it is a synonym — a misspelled species can fall back to its genus or kingdom at a confidence above 90, and a bare genus name carries the label too, matched as that genus. A name with no backbone match yields matchType NONE (no taxonKey) instead of failing the batch, with a note carrying GBIF's explanation when it gives one, such as several equal matches for a name shared across kingdoms; a per-name lookup failure yields matchType ERROR carrying that name's error message and, when the failure was classified, a machine-readable reason — the rest of the batch is unaffected, and the call as a whole still succeeds. When the name GBIF matched is a synonym — the queried name, or the higher taxon a HIGHERRANK match falls back to — taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key. Common names are not supported — use gbif_search_species for vernacular searches. Below confidence 80, review the match.

Count occurrences matching a taxon + location filter without fetching records. Use for quick totals ("how many Aves records in Sweden?") or before deciding whether to paginate a full search. Accepts taxonKey, country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, gadmGid, scientificName, spatial ranges and geometry (intersected), month, basisOfRecord, hasCoordinate (alias isGeoreferenced), isInCluster, coordinateUncertaintyInMeters, datasetKey, year, catalogNumber, institutionCode, recordedBy, mediaType, occurrenceStatus, and iucnRedListCategory. Counts sightings only by default, matching gbif_search_occurrences — GBIF also indexes absence records, and for some taxa they are the overwhelming majority. A count above 100,001 is the signal to partition rather than page: gbif_search_occurrences cannot reach past that offset, so split the query by DATASET_KEY via gbif_occurrence_facets and search each dataset separately.

Fetch full dataset metadata by UUID key — title, description, citation text, contacts, license, DOI, record count, numConstituents (sub-datasets), temporal/geographic coverage, and the publishing organization key, which gbif_search_datasets takes as publishingOrg. Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail. Contacts are capped by contactLimit (default 10); contactsTotal and contactsReturned report the full count.

Fetch a single occurrence record by its GBIF occurrence key. Returns the complete Darwin Core record — all coordinates, administrative geography (GADM levels 0–3), dates, collections metadata, collector identifiers, conservation status, media links, and quality issue flags. Check occurrenceStatus before reading the record as a sighting: ABSENT means a survey looked for the taxon and did not find it. Use the occurrence key from gbif_search_occurrences results.

Fetch a single backbone taxon by its GBIF taxon key. Returns full classification, authorship, taxonomic status, vernacular name, descendant count, and publication reference. Use after gbif_match_species when you need the complete record rather than the match summary. When taxonomicStatus is SYNONYM, acceptedKey and accepted fields identify the accepted taxon. The extinct field is absent (not false) on most records — only present on explicitly flagged taxa.

List direct children of a backbone taxon — genera within a family, species within a genus, subspecies within a species. Paginated. Use gbif_match_species to get the taxonKey first, then iterate with offset for large groups.

Return the parent chain for a taxon — from kingdom (or domain) down to the immediate parent of the queried taxon — as an ordered array. Each entry has its rank, canonical name, and taxon key. The array is returned root-first (kingdom → phylum → class → … → immediate parent of the queried taxon); the queried taxon itself is not included — call gbif_get_species for its own record. Useful for building taxonomic trees or understanding placement without navigating the backbone level-by-level.

Match a scientific name against the GBIF backbone taxonomy. Returns the best-matching taxon with full classification and a confidence score (0–100). This is the mandatory first step for any GBIF workflow — it returns the backbone taxonKey required by gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets. When the name GBIF matched is a synonym — the queried name, or the higher taxon a HIGHERRANK match falls back to — taxonKey is the accepted taxon it resolves to and matchedTaxonKey carries the synonym's own key; occurrence counts differ sharply between the two, so pass taxonKey. matchType HIGHERRANK is GBIF's label for a match made at a higher rank: a misspelled or unknown species falls back to its genus or even its kingdom, at a confidence that can exceed 90, and a bare genus name carries the label too, matched as that genus. taxonKey then covers that whole taxon, or its accepted taxon when it is a synonym, and a notice names it. Below confidence 80, the match should be reviewed. matchType NONE means no usable match was found — try removing the strict flag or broadening the name; when GBIF reports several equal matches, as for a genus name shared by an animal and a plant, set kingdom to pick one.

Aggregate occurrence counts across a dimension (COUNTRY, STATE_PROVINCE, YEAR, BASIS_OF_RECORD, DATASET_KEY, KINGDOM_KEY, etc.). Returns one page of facet values ranked by count descending — the top facetLimit at facetOffset 0, a later slice of the same ranking past that. No record payloads returned. Core tool for distribution analysis and trend queries: "which countries have the most records for this species?", "how has observation volume changed since 2010?". Key dimensions (KINGDOM_KEY through SPECIES_KEY, DATASET_KEY) return bare keys; includeLabels names the taxon or dataset behind each one on the page. Scope the aggregation with taxonKey, country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, gadmGid, year, scientificName, latitude/longitude ranges, month, hasCoordinate, isInCluster, coordinateUncertaintyInMeters, geometry (all spatial filters intersect), basisOfRecord, datasetKey, catalogNumber, institutionCode, recordedBy, mediaType, occurrenceStatus, or iucnRedListCategory filters. Also the way to split a result set too large for gbif_search_occurrences to page (offset+limit caps at 100,001): facet by DATASET_KEY, then search each datasetKey on its own. Aggregates sightings only by default, matching gbif_search_occurrences and gbif_count_occurrences; to measure the presence/absence split itself, pass facet OCCURRENCE_STATUS with occurrenceStatus ANY.

Search GBIF datasets by keyword, type, publishing country (uppercase ISO 3166-1 alpha-2), publishing organization, or hosting organization. The two organization filters answer different questions — publishingOrg matches the organization whose data it is, hostingOrg the organization whose installation serves it — and an organization key from gbif_search_publishers usually wants publishingOrg. Returns dataset title, description, license, record count, DOI, and the publishing organization's key and name; the key goes back in as publishingOrg. Use to find the source dataset behind a set of records, or to explore what data collections are available for a taxon, country, or organization.

Search GBIF occurrence records with Darwin Core filters. Use taxonKey from gbif_match_species for reliable results — it resolves synonyms automatically. Accepts country (uppercase ISO 3166-1 alpha-2, where the record was observed), publishingCountry (the publishing organization's country — a different question), stateProvince, gadmGid (a GADM administrative-area code GBIF derives from coordinates), bounding box (decimalLatitude/decimalLongitude ranges), WKT polygon geometry, year range, month, basis of record, coordinate filter, dataset key, catalogNumber, institutionCode, recordedBy (collector), and mediaType. Returns sightings only by default — GBIF also indexes absence records (surveys that looked and found nothing), and occurrenceStatus controls whether they are included. Pagination is capped at offset+limit=100,001 and GBIF offers no cursor or scroll, so a larger result set is covered only by partitioning it — facet it by DATASET_KEY with gbif_occurrence_facets and search each datasetKey separately. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free second cuts for a dataset bucket still over the cap; YEAR, MONTH, STATE_PROVINCE, and SPECIES_KEY lose records lacking that dimension. Repeat every biological filter on the facet call and each partition search, including the same occurrenceStatus, and compare sub-split sums against the bucket total. Bulk retrieval is outside this server: use the asynchronous GBIF Download API with a GBIF.org account or the monthly GBIF Parquet snapshot on AWS Open Data.

Search organizations registered with GBIF by name fragment or country. Returns organization key, title, and country — sufficient to chain into gbif_search_datasets as publishingOrg for the datasets an organization published, or as hostingOrg for the ones its own installation serves, or to understand who publishes data for a region. publishingOrg is the usual chain: most organizations publish through an installation someone else runs, so hostingOrg matches nothing for them.

Search or browse the GBIF backbone taxonomy by default, or an explicit checklist datasetKey. Accepts scientific name fragments, rank filters, and higher-taxon constraints. Useful for exploring what species exist under a higher taxon (e.g., "list all families of Coleoptera"), for simple name-fragment searches, or when gbif_match_species returns too narrow a result. kingdom, family, and genus scope the browse to a higher taxon: each is resolved to its backbone key before the search runs, so the narrowest one supplied is what scopes, an alternative name resolves to the taxon it is a synonym of, and a name that matches no backbone taxon at that rank fails rather than returning the whole index. Names are capitalized as GBIF writes them ("Paridae", not "paridae") and are matched exactly, not fuzzily. Paginated — use limit and offset to walk through results.