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

Official13 toolsLive

by cyanheads · TypeScript

Search GBIF species taxonomy, occurrence records, datasets, and publishers.

@cyanheads/gbif-biodiversity-mcp-server

This MCP server provides search capabilities for GBIF biodiversity resources, including species taxonomy, occurrence records, datasets, and publishers. It exposes 13 tools and can be run via STDIO or Streamable HTTP, based on the server’s interface description.

🛠️ Key Features

Search GBIF species taxonomy
Search GBIF occurrence records
Search GBIF datasets
Search GBIF publishers
Implements Model Context Protocol (MCP)
13 tools available

🚀 Use Cases

Query natural-history biodiversity information from GBIF
Retrieve taxonomic and occurrence-related records
Find datasets and identify relevant GBIF publishers

⚡ Developer Benefits

Supports MCP integration for structured querying
Works over STDIO or Streamable HTTP
Uses developer-focused technologies listed for the project (TypeScript, MCP)

⚠️ Limitations

Described capabilities are limited to GBIF taxonomy, occurrences, datasets, and publishers; no other data sources are stated.

Topics

biodiversitybundarwin-coregbifmcpmcp-servermodel-context-protocolnatural-historyoccurrencesspeciestaxonomytypescriptcyanheads

Captured live from the server via tools/list.

gbif_match_species

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 queried name is a synonym, 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. 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.

Parameters4

name	string	required	Scientific name to match. Examples: "Parus major", "Agaricus bisporus", "Homo sapiens". Fuzzy matching handles minor spelling variations. Common names are not supported — use gbif_search_species for vernacular name searches.
strict	boolean	optional	When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names.
kingdom	string	optional	Narrow the match to a specific kingdom (e.g., "Animalia", "Plantae", "Fungi") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom.
rank	string	optional	Expected taxonomic rank. Use to avoid matching a genus when you expect a species.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Scientific name to match. Examples: \"Parus major\", \"Agaricus bisporus\", \"Homo sapiens\". Fuzzy matching handles minor spelling variations. Common names are not supported — use gbif_search_species for vernacular name searches."
    },
    "strict": {
      "default": false,
      "description": "When true, only return an exact match. When false (default), GBIF applies fuzzy matching — useful for minor spelling variations and abbreviated names.",
      "type": "boolean"
    },
    "kingdom": {
      "description": "Narrow the match to a specific kingdom (e.g., \"Animalia\", \"Plantae\", \"Fungi\") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom.",
      "type": "string"
    },
    "rank": {
      "description": "Expected taxonomic rank. Use to avoid matching a genus when you expect a species.",
      "type": "string",
      "enum": [
        "KINGDOM",
        "PHYLUM",
        "CLASS",
        "ORDER",
        "FAMILY",
        "GENUS",
        "SPECIES",
        "SUBSPECIES"
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_bulk_match_species

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 name. A name with no backbone match yields matchType NONE (no taxonKey) instead of failing the batch; 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 a queried name is a synonym, 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.

Parameters2

names	array	required	Scientific names to match against the GBIF backbone. 1–50 per call, matched in parallel.
strict	boolean	optional	When true, require an exact match for every name (no fuzzy matching). When false (default), GBIF applies fuzzy matching to tolerate minor misspellings.

Raw schema

{
  "type": "object",
  "properties": {
    "names": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "A scientific name to match, e.g. \"Panthera leo\"."
      },
      "description": "Scientific names to match against the GBIF backbone. 1–50 per call, matched in parallel."
    },
    "strict": {
      "default": false,
      "description": "When true, require an exact match for every name (no fuzzy matching). When false (default), GBIF applies fuzzy matching to tolerate minor misspellings.",
      "type": "boolean"
    }
  },
  "required": [
    "names"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_get_species

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.

Parameters1

taxonKey

number

required

GBIF backbone taxon key from gbif_match_species or another taxonomy tool.

Raw schema

{
  "type": "object",
  "properties": {
    "taxonKey": {
      "type": "number",
      "description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
    }
  },
  "required": [
    "taxonKey"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_search_species

Search or browse the GBIF backbone taxonomy. 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.

Parameters9

q	string	optional	Name fragment to search for. Matches scientific and vernacular names. Omit the field to browse without a name term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with the whole 46,623,754-name index and a whitespace-only one with nothing, and neither is the search a caller who filled the field was asking for.
rank	string	optional	Filter to a specific taxonomic rank.
kingdom	string	optional	Scope the search to a kingdom, by name — "Animalia", "Plantae", "Fungi". Resolved to its backbone key before the search runs, and matched exactly: capitalize it as GBIF writes it, since "animalia" resolves to nothing. Supplied alongside family or genus it disambiguates that name rather than scoping on its own — "Prunella" alone names both a bird genus and a plant genus and resolves to neither. Omit the field to browse every kingdom; a blank or whitespace-only value is rejected rather than dropped.
family	string	optional	Scope the search to a family, by name — "Paridae", "Fagaceae". Resolved to its backbone key before the search runs, so an alternative family name lands on the taxon it is a synonym of ("Compositae" scopes to Asteraceae). Matched exactly and capitalized as GBIF writes it; a name that is not a backbone family fails rather than being ignored. Supplied with genus, it must be that genus's own family. Omit the field to browse every family; a blank or whitespace-only value is rejected rather than dropped.
genus	string	optional	Scope the search to a genus, by name — "Quercus", "Parus". Resolved to its backbone key before the search runs, and it is the narrowest of the three, so it is what scopes when kingdom or family is supplied too. Matched exactly and capitalized as GBIF writes it; a name shared across kingdoms ("Prunella", "Oenanthe") resolves only when kingdom is supplied with it. Omit the field to browse every genus; a blank or whitespace-only value is rejected rather than dropped.
isExtinct	boolean	optional	Filter to extinct (true) or extant (false) taxa.
datasetKey	string	optional	Scope to a specific checklist dataset UUID (8-4-4-4-12 hex). Omit the field to search the GBIF backbone — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered backbone result.
limit	number	optional	Number of records to return (default 20, max 1000).
offset	number	optional	Pagination offset.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Name fragment to search for. Matches scientific and vernacular names. Omit the field to browse without a name term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with the whole 46,623,754-name index and a whitespace-only one with nothing, and neither is the search a caller who filled the field was asking for.",
      "type": "string"
    },
    "rank": {
      "description": "Filter to a specific taxonomic rank.",
      "type": "string",
      "enum": [
        "KINGDOM",
        "PHYLUM",
        "CLASS",
        "ORDER",
        "FAMILY",
        "GENUS",
        "SPECIES",
        "SUBSPECIES"
      ]
    },
    "kingdom": {
      "description": "Scope the search to a kingdom, by name — \"Animalia\", \"Plantae\", \"Fungi\". Resolved to its backbone key before the search runs, and matched exactly: capitalize it as GBIF writes it, since \"animalia\" resolves to nothing. Supplied alongside family or genus it disambiguates that name rather than scoping on its own — \"Prunella\" alone names both a bird genus and a plant genus and resolves to neither. Omit the field to browse every kingdom; a blank or whitespace-only value is rejected rather than dropped.",
      "type": "string"
    },
    "family": {
      "description": "Scope the search to a family, by name — \"Paridae\", \"Fagaceae\". Resolved to its backbone key before the search runs, so an alternative family name lands on the taxon it is a synonym of (\"Compositae\" scopes to Asteraceae). Matched exactly and capitalized as GBIF writes it; a name that is not a backbone family fails rather than being ignored. Supplied with genus, it must be that genus's own family. Omit the field to browse every family; a blank or whitespace-only value is rejected rather than dropped.",
      "type": "string"
    },
    "genus": {
      "description": "Scope the search to a genus, by name — \"Quercus\", \"Parus\". Resolved to its backbone key before the search runs, and it is the narrowest of the three, so it is what scopes when kingdom or family is supplied too. Matched exactly and capitalized as GBIF writes it; a name shared across kingdoms (\"Prunella\", \"Oenanthe\") resolves only when kingdom is supplied with it. Omit the field to browse every genus; a blank or whitespace-only value is rejected rather than dropped.",
      "type": "string"
    },
    "isExtinct": {
      "description": "Filter to extinct (true) or extant (false) taxa.",
      "type": "boolean"
    },
    "datasetKey": {
      "description": "Scope to a specific checklist dataset UUID (8-4-4-4-12 hex). Omit the field to search the GBIF backbone — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered backbone result.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Number of records to return (default 20, max 1000).",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_get_species_classification

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.

Parameters1

taxonKey

number

required

GBIF backbone taxon key from gbif_match_species or another taxonomy tool.

Raw schema

{
  "type": "object",
  "properties": {
    "taxonKey": {
      "type": "number",
      "description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
    }
  },
  "required": [
    "taxonKey"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_get_species_children

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.

Parameters3

taxonKey	number	required	GBIF backbone taxon key from gbif_match_species or another taxonomy tool.
limit	number	optional	Number of children to return (default 20, max 1000).
offset	number	optional	Pagination offset.

Raw schema

{
  "type": "object",
  "properties": {
    "taxonKey": {
      "type": "number",
      "description": "GBIF backbone taxon key from gbif_match_species or another taxonomy tool."
    },
    "limit": {
      "default": 20,
      "description": "Number of children to return (default 20, max 1000).",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "taxonKey"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_search_occurrences

Search 3.9B+ 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, bounding box (decimalLatitude/decimalLongitude ranges), WKT polygon geometry, year range, month, basis of record, coordinate filter, and dataset key. 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. This server cannot download a result set in bulk; that needs the GBIF Download API with a GBIF.org account, or the GBIF snapshot on AWS Open Data.

Parameters19

taxonKey	number	optional	GBIF backbone taxon key from gbif_match_species. Preferred over scientificName — matches all synonyms automatically. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).
scientificName	string	optional	Scientific name filter. Less precise than taxonKey — does not match synonyms. Use taxonKey from gbif_match_species for reliable results. Supplying both does not narrow the search: GBIF combines the two taxon filters with OR, so the result is the union of the two, not their intersection. Omit the field to search every name — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
country	string	optional	ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., "GB", "US", "DE", "SE"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know ("XX") is rejected upstream by name.
publishingCountry	string	optional	ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.
stateProvince	string	optional	State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value returns zero records rather than an error. Omit the field to search every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. Records carrying no stateProvince match no value, so this cannot partition a scope.
decimalLatitude	string	optional	Latitude range as "min,max" (e.g., "47.0,48.5"). Decimal degrees, WGS84. Combine with decimalLongitude for a bounding box. Omit the field to leave latitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
decimalLongitude	string	optional	Longitude range as "min,max" (e.g., "8.0,9.5"). Decimal degrees, WGS84. Combine with decimalLatitude for a bounding box. Omit the field to leave longitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
geometry	string	optional	WKT polygon for geographic filtering (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Takes precedence over decimalLatitude/decimalLongitude. Omit the field to search everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
year	string	optional	Year or year range. Single year: "2024". Range: "2020,2024". Filters by observation year. Both endpoints inclusive. Omit the field to search every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
month	number	optional	Calendar month (1–12). Useful for seasonal distribution queries.
basisOfRecord	string	optional	Filter by how the occurrence was recorded. HUMAN_OBSERVATION covers citizen science. PRESERVED_SPECIMEN covers natural history collections.
hasCoordinate	boolean	optional	When true, return only georeferenced records (those with coordinates). When false, return ONLY records without coordinates. Omit the parameter entirely to include all records regardless of coordinate presence.
isInCluster	boolean	optional	Filter to records flagged as likely duplicates (true) or exclude them (false). Omit to include all. Note: GBIF does not expose a cluster identifier — only the membership flag. To de-duplicate, set isInCluster: false to exclude all clustered records.
coordinateUncertaintyInMeters	string	optional	Filter by coordinate uncertainty radius in meters. Range format: "min,max" (e.g., "0,1000" for sub-kilometer precision). Both endpoints inclusive. Omit the field to accept any uncertainty — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.
datasetKey	string	optional	Restrict results to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet (gbif_occurrence_facets), or the datasetKey field on an occurrence record. Omit the field to search every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered result set.
occurrenceStatus	string	optional	Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so including one would read as a sighting of the opposite. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone.
iucnRedListCategory	string	optional	Restrict to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set.
limit	number	optional	Number of records to return (default 20, max 300).
offset	number	optional	Pagination offset. GBIF serves offset+limit up to 100,001 and rejects anything past it, with no cursor or scroll to continue from. To reach a result set larger than that, split it into per-datasetKey searches using a DATASET_KEY facet from gbif_occurrence_facets — gap-free and high-cardinality, unlike YEAR, which leaves undated records in no bucket — rather than paging deeper.

Raw schema

{
  "type": "object",
  "properties": {
    "taxonKey": {
      "description": "GBIF backbone taxon key from gbif_match_species. Preferred over scientificName — matches all synonyms automatically. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).",
      "type": "number"
    },
    "scientificName": {
      "description": "Scientific name filter. Less precise than taxonKey — does not match synonyms. Use taxonKey from gbif_match_species for reliable results. Supplying both does not narrow the search: GBIF combines the two taxon filters with OR, so the result is the union of the two, not their intersection. Omit the field to search every name — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., \"GB\", \"US\", \"DE\", \"SE\"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know (\"XX\") is rejected upstream by name.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "publishingCountry": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "stateProvince": {
      "description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, and \"england\" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value returns zero records rather than an error. Omit the field to search every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set. Records carrying no stateProvince match no value, so this cannot partition a scope.",
      "type": "string"
    },
    "decimalLatitude": {
      "description": "Latitude range as \"min,max\" (e.g., \"47.0,48.5\"). Decimal degrees, WGS84. Combine with decimalLongitude for a bounding box. Omit the field to leave latitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "decimalLongitude": {
      "description": "Longitude range as \"min,max\" (e.g., \"8.0,9.5\"). Decimal degrees, WGS84. Combine with decimalLatitude for a bounding box. Omit the field to leave longitude unbounded — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "geometry": {
      "description": "WKT polygon for geographic filtering (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Takes precedence over decimalLatitude/decimalLongitude. Omit the field to search everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "year": {
      "description": "Year or year range. Single year: \"2024\". Range: \"2020,2024\". Filters by observation year. Both endpoints inclusive. Omit the field to search every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "month": {
      "description": "Calendar month (1–12). Useful for seasonal distribution queries.",
      "type": "number",
      "minimum": 1,
      "maximum": 12
    },
    "basisOfRecord": {
      "description": "Filter by how the occurrence was recorded. HUMAN_OBSERVATION covers citizen science. PRESERVED_SPECIMEN covers natural history collections.",
      "type": "string",
      "enum": [
        "HUMAN_OBSERVATION",
        "MACHINE_OBSERVATION",
        "PRESERVED_SPECIMEN",
        "LIVING_SPECIMEN",
        "MATERIAL_SAMPLE",
        "MATERIAL_CITATION",
        "OCCURRENCE",
        "LITERATURE"
      ]
    },
    "hasCoordinate": {
      "description": "When true, return only georeferenced records (those with coordinates). When false, return ONLY records without coordinates. Omit the parameter entirely to include all records regardless of coordinate presence.",
      "type": "boolean"
    },
    "isInCluster": {
      "description": "Filter to records flagged as likely duplicates (true) or exclude them (false). Omit to include all. Note: GBIF does not expose a cluster identifier — only the membership flag. To de-duplicate, set isInCluster: false to exclude all clustered records.",
      "type": "boolean"
    },
    "coordinateUncertaintyInMeters": {
      "description": "Filter by coordinate uncertainty radius in meters. Range format: \"min,max\" (e.g., \"0,1000\" for sub-kilometer precision). Both endpoints inclusive. Omit the field to accept any uncertainty — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered result set.",
      "type": "string"
    },
    "datasetKey": {
      "description": "Restrict results to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet (gbif_occurrence_facets), or the datasetKey field on an occurrence record. Omit the field to search every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered result set.",
      "type": "string"
    },
    "occurrenceStatus": {
      "default": "PRESENT",
      "description": "Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so including one would read as a sighting of the opposite. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone.",
      "type": "string",
      "enum": [
        "PRESENT",
        "ABSENT",
        "ANY"
      ]
    },
    "iucnRedListCategory": {
      "description": "Restrict to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set.",
      "type": "string",
      "enum": [
        "CR",
        "EN",
        "VU",
        "NT",
        "LC",
        "DD",
        "EX",
        "EW",
        "CD"
      ]
    },
    "limit": {
      "default": 20,
      "description": "Number of records to return (default 20, max 300).",
      "type": "number",
      "minimum": 1,
      "maximum": 300
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset. GBIF serves offset+limit up to 100,001 and rejects anything past it, with no cursor or scroll to continue from. To reach a result set larger than that, split it into per-datasetKey searches using a DATASET_KEY facet from gbif_occurrence_facets — gap-free and high-cardinality, unlike YEAR, which leaves undated records in no bucket — rather than paging deeper.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_count_occurrences

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, isGeoreferenced, datasetKey, year, 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.

Parameters9

taxonKey	number	optional	GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).
country	string	optional	ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., "GB", "US"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know ("XX") is rejected upstream by name.
publishingCountry	string	optional	ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.
stateProvince	string	optional	State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring. Omit the field to count across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.
isGeoreferenced	boolean	optional	When true, count only georeferenced records. When false, count only non-georeferenced records.
datasetKey	string	optional	Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. Omit the field to count across every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered total. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default.
year	string	optional	Year or year range (e.g., "2024" or "2020,2024"). Both endpoints inclusive. Omit the field to count across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.
occurrenceStatus	string	optional	Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so counting one inflates the total with the opposite of a sighting. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone. Matches the gbif_search_occurrences default, so the two tools agree.
iucnRedListCategory	string	optional	Count only records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set.

Raw schema

{
  "type": "object",
  "properties": {
    "taxonKey": {
      "description": "GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).",
      "type": "number"
    },
    "country": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., \"GB\", \"US\"). Not the publisher's country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know (\"XX\") is rejected upstream by name.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "publishingCountry": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "stateProvince": {
      "description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, and \"england\" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring. Omit the field to count across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.",
      "type": "string"
    },
    "isGeoreferenced": {
      "description": "When true, count only georeferenced records. When false, count only non-georeferenced records.",
      "type": "boolean"
    },
    "datasetKey": {
      "description": "Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. Omit the field to count across every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered total. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default.",
      "type": "string"
    },
    "year": {
      "description": "Year or year range (e.g., \"2024\" or \"2020,2024\"). Both endpoints inclusive. Omit the field to count across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.",
      "type": "string"
    },
    "occurrenceStatus": {
      "default": "PRESENT",
      "description": "Presence/absence filter. Defaults to PRESENT: an ABSENT record documents a survey that looked for the taxon and did not find it, so counting one inflates the total with the opposite of a sighting. Use ANY for both (GBIF's own default), or ABSENT for non-observations alone. Matches the gbif_search_occurrences default, so the two tools agree.",
      "type": "string",
      "enum": [
        "PRESENT",
        "ABSENT",
        "ANY"
      ]
    },
    "iucnRedListCategory": {
      "description": "Count only records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Records with no category are excluded when this is set.",
      "type": "string",
      "enum": [
        "CR",
        "EN",
        "VU",
        "NT",
        "LC",
        "DD",
        "EX",
        "EW",
        "CD"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_get_occurrence

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.

Parameters1

occurrenceKey

number

required

GBIF occurrence key from gbif_search_occurrences results.

Raw schema

{
  "type": "object",
  "properties": {
    "occurrenceKey": {
      "type": "number",
      "description": "GBIF occurrence key from gbif_search_occurrences results."
    }
  },
  "required": [
    "occurrenceKey"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_occurrence_facets

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?". Scope the aggregation with taxonKey, country (uppercase ISO 3166-1 alpha-2), publishingCountry, stateProvince, year, geometry, basisOfRecord, datasetKey, 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.

Parameters13

facet	string	required	Dimension to aggregate by (e.g., COUNTRY, YEAR, BASIS_OF_RECORD, SPECIES_KEY, OCCURRENCE_STATUS, IUCN_RED_LIST_CATEGORY). DATASET_KEY is the dimension to split on when a result set is too large to page: every occurrence carries exactly one datasetKey, so its buckets sum to totalOccurrences with no gap and no overlap, and it has the cardinality to cut a large scope into pageable pieces. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free too and both have a matching filter on the occurrence tools, so either can drive a further split of a bucket still too large — but on that same scope they return 9 and 41 buckets against DATASET_KEY's 550, so neither replaces it as the first cut. A dimension a record can lack silently drops that record: faceting one 60,290,950-record scope by YEAR returned 224 buckets summing to 59,407,400, leaving 883,550 undated records in no bucket at all, and MONTH, STATE_PROVINCE, and SPECIES_KEY lose records the same way — stateProvince included, even though the occurrence tools can now filter on it. Sums are comparable only across the same occurrenceStatus scope.
taxonKey	number	optional	Backbone taxon key to scope the aggregation. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).
country	string	optional	ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded, to scope to one country. Not the publisher's country — that is publishingCountry, and the two disagree on most records. Scope to one country, or pass back a value this tool returned under facet COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.
publishingCountry	string	optional	ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. Scope to one publisher country, or pass back a value this tool returned under facet PUBLISHING_COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.
stateProvince	string	optional	State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so "England", "England - Greater London", and "Greater London" are three distinct values, "england" is none of them, and an unmatched value aggregates zero records rather than erroring. Omit the field to aggregate across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.
year	string	optional	Year or year range (e.g., "2020,2024") to scope the aggregation. Both endpoints inclusive. Omit the field to aggregate across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.
basisOfRecord	string	optional	Scope to a specific basis of record.
geometry	string	optional	WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Omit the field to aggregate everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.
datasetKey	string	optional	Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record. Omit the field to aggregate across every dataset — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered aggregation.
occurrenceStatus	string	optional	Presence/absence scope. Defaults to PRESENT so the aggregation counts sightings, not the surveys that looked and found nothing, and agrees with gbif_count_occurrences on the same filters. Use ANY for both — required to see both buckets when facet is OCCURRENCE_STATUS — or ABSENT for non-observations alone.
iucnRedListCategory	string	optional	Scope to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Leave unset and facet on IUCN_RED_LIST_CATEGORY to see the whole distribution instead.
facetLimit	number	optional	Maximum number of facet values to return (default 10, max 100).
facetOffset	number	optional	Zero-based offset into the ranked facet values, for paging past the first facetLimit values on high-cardinality dimensions like DATASET_KEY. Advance by facetLimit to fetch the next page (0, then facetLimit, then 2×facetLimit, …).

Raw schema

{
  "type": "object",
  "properties": {
    "facet": {
      "type": "string",
      "enum": [
        "BASIS_OF_RECORD",
        "COUNTRY",
        "STATE_PROVINCE",
        "YEAR",
        "DATASET_KEY",
        "KINGDOM_KEY",
        "PHYLUM_KEY",
        "CLASS_KEY",
        "ORDER_KEY",
        "FAMILY_KEY",
        "GENUS_KEY",
        "SPECIES_KEY",
        "PUBLISHING_COUNTRY",
        "MONTH",
        "OCCURRENCE_STATUS",
        "IUCN_RED_LIST_CATEGORY"
      ],
      "description": "Dimension to aggregate by (e.g., COUNTRY, YEAR, BASIS_OF_RECORD, SPECIES_KEY, OCCURRENCE_STATUS, IUCN_RED_LIST_CATEGORY). DATASET_KEY is the dimension to split on when a result set is too large to page: every occurrence carries exactly one datasetKey, so its buckets sum to totalOccurrences with no gap and no overlap, and it has the cardinality to cut a large scope into pageable pieces. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free too and both have a matching filter on the occurrence tools, so either can drive a further split of a bucket still too large — but on that same scope they return 9 and 41 buckets against DATASET_KEY's 550, so neither replaces it as the first cut. A dimension a record can lack silently drops that record: faceting one 60,290,950-record scope by YEAR returned 224 buckets summing to 59,407,400, leaving 883,550 undated records in no bucket at all, and MONTH, STATE_PROVINCE, and SPECIES_KEY lose records the same way — stateProvince included, even though the occurrence tools can now filter on it. Sums are comparable only across the same occurrenceStatus scope."
    },
    "taxonKey": {
      "description": "Backbone taxon key to scope the aggregation. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).",
      "type": "number"
    },
    "country": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded, to scope to one country. Not the publisher's country — that is publishingCountry, and the two disagree on most records. Scope to one country, or pass back a value this tool returned under facet COUNTRY to drill into that bucket. Lowercase and alpha-3 forms (\"gb\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "publishingCountry": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. Scope to one publisher country, or pass back a value this tool returned under facet PUBLISHING_COUNTRY to drill into that bucket. Lowercase and alpha-3 forms (\"us\", \"USA\") match nothing upstream, which is why only the uppercase two-letter form is accepted here.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "stateProvince": {
      "description": "State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so \"England\", \"England - Greater London\", and \"Greater London\" are three distinct values, \"england\" is none of them, and an unmatched value aggregates zero records rather than erroring. Omit the field to aggregate across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.",
      "type": "string"
    },
    "year": {
      "description": "Year or year range (e.g., \"2020,2024\") to scope the aggregation. Both endpoints inclusive. Omit the field to aggregate across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.",
      "type": "string"
    },
    "basisOfRecord": {
      "description": "Scope to a specific basis of record.",
      "type": "string",
      "enum": [
        "HUMAN_OBSERVATION",
        "MACHINE_OBSERVATION",
        "PRESERVED_SPECIMEN",
        "LIVING_SPECIMEN",
        "MATERIAL_SAMPLE",
        "MATERIAL_CITATION",
        "OCCURRENCE",
        "LITERATURE"
      ]
    },
    "geometry": {
      "description": "WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Omit the field to aggregate everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.",
      "type": "string"
    },
    "datasetKey": {
      "description": "Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record. Omit the field to aggregate across every dataset — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered aggregation.",
      "type": "string"
    },
    "occurrenceStatus": {
      "default": "PRESENT",
      "description": "Presence/absence scope. Defaults to PRESENT so the aggregation counts sightings, not the surveys that looked and found nothing, and agrees with gbif_count_occurrences on the same filters. Use ANY for both — required to see both buckets when facet is OCCURRENCE_STATUS — or ABSENT for non-observations alone.",
      "type": "string",
      "enum": [
        "PRESENT",
        "ABSENT",
        "ANY"
      ]
    },
    "iucnRedListCategory": {
      "description": "Scope to records whose taxon carries this IUCN Red List category: CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. Leave unset and facet on IUCN_RED_LIST_CATEGORY to see the whole distribution instead.",
      "type": "string",
      "enum": [
        "CR",
        "EN",
        "VU",
        "NT",
        "LC",
        "DD",
        "EX",
        "EW",
        "CD"
      ]
    },
    "facetLimit": {
      "default": 10,
      "description": "Maximum number of facet values to return (default 10, max 100).",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "facetOffset": {
      "default": 0,
      "description": "Zero-based offset into the ranked facet values, for paging past the first facetLimit values on high-cardinality dimensions like DATASET_KEY. Advance by facetLimit to fetch the next page (0, then facetLimit, then 2×facetLimit, …).",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "facet"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_search_datasets

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, and DOI. 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.

Parameters7

q	string	optional	Free-text search across dataset title and description. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with all 123,527 indexed datasets and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for.
type	string	optional	Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists.
publishingCountry	string	optional	ISO 3166-1 alpha-2 code, uppercase, of the organization that published the dataset (e.g., "GB", "US", "DE", "SE"). Lowercase and alpha-3 forms ("gb", "GBR") match nothing upstream, which is why only the uppercase two-letter form is accepted here — unlike the country filter on gbif_search_publishers, which resolves either form. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not assign ("XX") is rejected upstream by name.
publishingOrg	string	optional	UUID (8-4-4-4-12 hex, lowercase — GBIF matches these two keys case-sensitively, so an upper-cased rendering of a real key matches nothing) of the organization that published the dataset — the organization whose data it is, and the question a key from gbif_search_publishers is usually asking. Not the organization that serves it, which is hostingOrg and matches a different set: Butterfly Conservation (0d72dd7f-6f05-46af-85c2-8b6e77ce5534) publishes 3 datasets and hosts none, while the National Biodiversity Network (07f617d0-c688-11d8-bf62-b8a03c50a862) hosts 984 — those 3 among them — and publishes 1. Supplied together the two filters are intersected, not combined, so the same key in both fields returns only what that organization both published and serves.
hostingOrg	string	optional	UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — not the organization that published it, which is publishingOrg. Most organizations publish through an installation someone else runs, so a key from gbif_search_publishers matches nothing here for them: of the first 25 GB organizations the registry lists, all 25 host no datasets while 13 publish one or two. Supplied together the two filters are intersected, not combined.
limit	number	optional	Number of datasets to return (default 20, max 1000).
offset	number	optional	Pagination offset.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Free-text search across dataset title and description. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because GBIF answers a blank one with all 123,527 indexed datasets and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for.",
      "type": "string"
    },
    "type": {
      "description": "Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists.",
      "type": "string",
      "enum": [
        "OCCURRENCE",
        "CHECKLIST",
        "METADATA",
        "SAMPLING_EVENT"
      ]
    },
    "publishingCountry": {
      "description": "ISO 3166-1 alpha-2 code, uppercase, of the organization that published the dataset (e.g., \"GB\", \"US\", \"DE\", \"SE\"). Lowercase and alpha-3 forms (\"gb\", \"GBR\") match nothing upstream, which is why only the uppercase two-letter form is accepted here — unlike the country filter on gbif_search_publishers, which resolves either form. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not assign (\"XX\") is rejected upstream by name.",
      "type": "string",
      "pattern": "^[A-Z]{2}$"
    },
    "publishingOrg": {
      "description": "UUID (8-4-4-4-12 hex, lowercase — GBIF matches these two keys case-sensitively, so an upper-cased rendering of a real key matches nothing) of the organization that published the dataset — the organization whose data it is, and the question a key from gbif_search_publishers is usually asking. Not the organization that serves it, which is hostingOrg and matches a different set: Butterfly Conservation (0d72dd7f-6f05-46af-85c2-8b6e77ce5534) publishes 3 datasets and hosts none, while the National Biodiversity Network (07f617d0-c688-11d8-bf62-b8a03c50a862) hosts 984 — those 3 among them — and publishes 1. Supplied together the two filters are intersected, not combined, so the same key in both fields returns only what that organization both published and serves.",
      "type": "string"
    },
    "hostingOrg": {
      "description": "UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — not the organization that published it, which is publishingOrg. Most organizations publish through an installation someone else runs, so a key from gbif_search_publishers matches nothing here for them: of the first 25 GB organizations the registry lists, all 25 host no datasets while 13 publish one or two. Supplied together the two filters are intersected, not combined.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Number of datasets to return (default 20, max 1000).",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_get_dataset

Fetch full dataset metadata by UUID key — title, description, citation text, contacts, license, DOI, record count, numConstituents (sub-datasets), and temporal/geographic coverage. 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.

Parameters2

datasetKey	string	required	Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record.
contactLimit	integer	optional	Maximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal — useful when citation, license, and record count are all you need from a high-contact dataset like eBird.

Raw schema

{
  "type": "object",
  "properties": {
    "datasetKey": {
      "type": "string",
      "description": "Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record."
    },
    "contactLimit": {
      "default": 10,
      "description": "Maximum number of contacts to include (default 10, max 100). Set to 0 to omit contact detail while still reporting contactsTotal — useful when citation, license, and record count are all you need from a high-contact dataset like eBird.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    }
  },
  "required": [
    "datasetKey"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

gbif_search_publishers

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.

Parameters4

q	string	optional	Name fragment to search for. Matches organization names. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because the registry answers either with all 3,561 registered organizations.
country	string	optional	ISO 3166-1 country code to filter organizations by country. The alpha-2 form ("GB") is canonical; unlike the country codes on the occurrence tools and gbif_search_datasets, this one also resolves the alpha-3 form ("GBR") and is case-insensitive, because the registry endpoint matches the parsed country rather than the string. A value GBIF cannot parse as a country errors rather than returning an empty list. Omit the field to search every country — an empty string is rejected rather than read as no filter, because the registry answers a blank country with all 3,561 organizations.
limit	number	optional	Number of organizations to return (default 20, max 1000).
offset	number	optional	Pagination offset.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "description": "Name fragment to search for. Matches organization names. Omit the field to browse without a term — a blank or whitespace-only value is rejected rather than sent, because the registry answers either with all 3,561 registered organizations.",
      "type": "string"
    },
    "country": {
      "description": "ISO 3166-1 country code to filter organizations by country. The alpha-2 form (\"GB\") is canonical; unlike the country codes on the occurrence tools and gbif_search_datasets, this one also resolves the alpha-3 form (\"GBR\") and is case-insensitive, because the registry endpoint matches the parsed country rather than the string. A value GBIF cannot parse as a country errors rather than returning an empty list. Omit the field to search every country — an empty string is rejected rather than read as no filter, because the registry answers a blank country with all 3,561 organizations.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Number of organizations to return (default 20, max 1000).",
      "type": "number",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md30 KBView on GitHub

@cyanheads/gbif-biodiversity-mcp-server

Search GBIF species taxonomy, occurrence records, datasets, and publishers via MCP. STDIO or Streamable HTTP.

13 Tools • 2 Resources

MCP SDK TypeScript

Public Hosted Server: https://gbif-biodiversity.caseyjhand.com/mcp

Overview

GBIF species taxonomy, occurrence records, datasets, and publishers. Match names to the backbone taxonomy, search 3.9B+ occurrence records with Darwin Core filters, and browse dataset and publisher metadata from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`gbif_match_species`	Match a species name against the GBIF backbone taxonomy — returns taxonKey, confidence score, and full classification
`gbif_bulk_match_species`	Match up to 50 scientific names to backbone taxon keys in one call — results in input order, per-name NONE/ERROR isolation
`gbif_get_species`	Fetch a single backbone taxon by key — full classification, authorship, synonymy, vernacular name, descendant count
`gbif_search_species`	Search or browse the GBIF backbone taxonomy by name fragment, rank, or a kingdom, family, or genus name resolved to its backbone key
`gbif_get_species_classification`	Return the root-to-parent classification chain for a taxon — root-first ordered array from kingdom to the queried taxon's immediate parent (the taxon itself is not included)
`gbif_get_species_children`	List direct children of a backbone taxon — genera within a family, species within a genus
`gbif_search_occurrences`	Search 3.9B+ GBIF occurrence records with Darwin Core filters — country, publishing country, state/province, bounding box, WKT geometry, year, month, basis of record, presence/absence, IUCN Red List category
`gbif_count_occurrences`	Count occurrences matching a filter without fetching records — fast single-number response, filtered to sightings by default
`gbif_get_occurrence`	Fetch a single occurrence record by key — full Darwin Core record with GADM geography, presence/absence status, conservation status, media, and quality flags
`gbif_occurrence_facets`	Aggregate occurrence counts by a dimension — country, year, basis of record, dataset, kingdom, presence/absence, IUCN Red List category
`gbif_search_datasets`	Search GBIF datasets by keyword, type, country, publishing organization, or hosting organization
`gbif_get_dataset`	Fetch full dataset metadata by UUID — title, description, citation, contacts, license, DOI, coverage
`gbif_search_publishers`	Search GBIF-registered publishing organizations by name fragment or country

Resources

Resource	Description
`gbif://species/{taxonKey}`	Taxon record from the GBIF backbone — classification, authorship, synonymy status, vernacular name
`gbif://dataset/{datasetKey}`	Dataset metadata — title, description, citation, license, contacts, coverage

Both resources are also reachable via gbif_get_species and gbif_get_dataset; many MCP clients are tool-only and never surface resources.

Capability reference

`gbif_match_species` _tool

Fuzzy matching handles minor typos and vernacular names; set strict: true for exact-only matching
Returns taxonKey — the backbone key required by gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets
Confidence score 0–100; below 80 warrants review
Full classification hierarchy with keys at each rank: kingdom, phylum, class, order, family, genus, species
matchType NONE indicates no usable match — try removing strict mode or broadening the name
Resolves synonyms: always returns the accepted backbone key regardless of which name form was queried; matchedTaxonKey carries the synonym's own key when the two differ
kingdom disambiguates a name that appears in more than one kingdom, and is rejected when supplied blank: GBIF drops a blank one and matches against the whole backbone — Parus major resolves to taxon 9705453 with kingdom= exactly as it does with no kingdom at all, where Plantae resolves to 9711704 — so the undisambiguated answer would come back looking like a disambiguated one. Omit the field to match against the whole backbone

`gbif_bulk_match_species` _tool

The batch counterpart to gbif_match_species — built for checklist, inventory, and species-list workflows that would otherwise need one round trip per name
Returns one result per input name, in input order; each carries taxonKey, matchType, and confidence
Per-name isolation: an unmatched name yields matchType NONE and a per-name lookup failure yields matchType ERROR with the message and, when the failure was classified, a reason — neither sinks the rest of the batch
Same synonym resolution as gbif_match_species: taxonKey is the accepted taxon, matchedTaxonKey the synonym it was queried under
strict: true requires an exact match for every name; common names are not supported (use gbif_search_species)

`gbif_get_species` _tool

Full classification, authorship string, and vernacular (English) name when available
taxonomicStatus: ACCEPTED, SYNONYM, DOUBTFUL — when SYNONYM, acceptedKey and accepted identify the current name
numDescendants and numOccurrences for scope at a glance
extinct field present only when explicitly flagged — not false on unlabeled taxa
publishedIn carries the original description citation when available

`gbif_search_species` _tool

Accepts name fragments matching scientific and vernacular names
Filter by rank, kingdom, family, or genus to scope browsing
kingdom, family, and genus are given as names and resolved to a backbone key before the search runs, since /species/search scopes by key alone. The narrowest one supplied is what scopes — the three nest, and GBIF combines two keys with OR rather than AND. kingdom supplied beside family or genus disambiguates that name instead of scoping on its own: Prunella names both a bird genus and a plant genus and resolves to neither without it
Names are matched exactly and capitalized as GBIF writes them, so paridae and Paridaee fail as unresolved_taxon_scope rather than being ignored. An alternative family name lands on the taxon it is a synonym of — Compositae scopes to Asteraceae. A family and genus in different lineages fail as conflicting_taxon_scope. The scope actually applied comes back in the enrichment
isExtinct filter for extinct vs. extant taxa
Scope to a specific checklist dataset with datasetKey — omit the field for the GBIF backbone. GBIF reads a higher-taxon key inside the checklist that key belongs to, so pairing datasetKey with a kingdom, family, or genus matches nothing unless the checklist is the backbone; the empty-result notice says so
q, kingdom, family, genus, and datasetKey are rejected when supplied blank rather than dropped: a blank datasetKey returns the unfiltered backbone result, and q= returns the whole 46,623,754-name index where q= with a space returns nothing. Omit a filter to leave it off
Paginated — limit up to 1000, use offset to walk through large groups

`gbif_get_species_classification` _tool

Root-first from kingdom down to the immediate parent of the queried taxon (kingdom → phylum → class → … → parent)
The queried taxon itself is not included — use gbif_get_species for its own record
Each entry: rank, canonical name, scientific name, taxon key
Useful for building taxonomic trees or placing an unfamiliar taxon in context without manual backbone navigation

`gbif_get_species_children` _tool

Genera within a family, species within a genus, subspecies within a species
Each child: key, name, rank, taxonomic status, common name, occurrence count, descendant count
Paginated — limit up to 1000, iterate with offset for large groups like Coleoptera

`gbif_search_occurrences` _tool

Use taxonKey from gbif_match_species for reliable results — resolves synonyms automatically; scientificName filter does not
Geographic filters: country (ISO 3166-1 alpha-2, uppercase), stateProvince, bounding box (decimalLatitude/decimalLongitude ranges as "min,max"), or WKT polygon (geometry)
publishingCountry (ISO 3166-1 alpha-2, uppercase) is the country of the publishing organization, not of the observation — a different question from country, and the two disagree on most records: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations
Both country filters take the uppercase two-letter form only. GBIF parses a lowercase or alpha-3 code and then matches the verbatim string, so gb and USA return zero records instead of an error; the schema pattern turns that silent wrong answer into a validation error naming the accepted form. A two-letter code GBIF does not assign (XX) is rejected upstream by name and surfaces as invalid_filter
stateProvince is matched verbatim — exact and case-sensitive, with no controlled vocabulary behind it. Take a value from a STATE_PROVINCE facet rather than guessing; an unmatched value returns zero records instead of an error, and the enrichment notice says so when it happens
Every filter is checked whenever it is supplied, not only when it holds a value. GBIF ignores a parameter it is given with no value and answers 200 with the unfiltered scope, so a blank filter used to widen the query silently: stateProvince: "" returns all 60,290,950 records of a taxonKey=212 + country=GB scope where England returns 47,672,439 — the same total, and the same first record, as a call that sends no stateProvince at all. A blank or whitespace-only value now fails as invalid_filter instead. Omit a field to leave that filter off
Temporal filters: year as single year or range, month (1–12) for seasonal queries
basisOfRecord enum: HUMAN_OBSERVATION, PRESERVED_SPECIMEN, MACHINE_OBSERVATION, and more
hasCoordinate to require or exclude georeferenced records
occurrenceStatus — PRESENT (default), ABSENT, or ANY. GBIF indexes absence records (a survey that looked for the taxon and did not find it) alongside sightings; the default excludes them and the enrichment says so on every call
iucnRedListCategory — CR, EN, VU, NT, LC, DD, EX, EW, CD
Output per record adds taxonomicStatus, eventTime (with UTC offset), occurrenceStatus, and iucnRedListCategory
Pagination capped at offset+limit = 100,001, the deepest page GBIF serves. The API has no cursor or scroll, so a larger result set is covered by partitioning it — facet by DATASET_KEY with gbif_occurrence_facets, then search each datasetKey on its own. Retrieving a set in one piece is not something this server can do: that needs GBIF's Download API with a GBIF.org account, or GBIF's monthly snapshot on AWS Open Data

`gbif_count_occurrences` _tool

Backed by /occurrence/search at limit=0 — no record payload, and the same endpoint gbif_search_occurrences queries, so the two agree on the same question. GBIF's dedicated /occurrence/count endpoint takes a closed parameter set that rejects occurrenceStatus and iucnRedListCategory outright
Supported filters: taxonKey, country, publishingCountry, stateProvince, isGeoreferenced, datasetKey, year, occurrenceStatus, iucnRedListCategory. country and publishingCountry take the uppercase alpha-2 form only, and a blank filter is rejected rather than dropped, both for the reasons given under gbif_search_occurrences
Counts sightings only by default, matching gbif_search_occurrences. For absence-heavy taxa the unfiltered figure is a different question entirely — Radicipes gracilis has 2,351,582 indexed records of which 79 are presences
Use to assess result set size before deciding whether to paginate a full search. A count above 100,001 means paging cannot reach the end of it, and the enrichment notice says so and names the partition route

`gbif_get_occurrence` _tool

Complete Darwin Core record — all coordinate fields, administrative geography (continent, country, state/province, locality), dates
occurrenceID, full classification (class/classKey), GADM administrative units (levels 0–3, each with a stable GID and name), and source identifiers
occurrenceStatus — check it before reading the record as a sighting; ABSENT means a survey looked and found nothing, and the record still carries coordinates, a date, and a recorder
taxonomicStatus, eventTime (with UTC offset), and iucnRedListCategory
Collections metadata: institution code, collection code, catalog number
Collector and identifier names, individual count, sex, life stage
Associated media (images, audio, video) with URLs and license
GBIF data quality issue flags for provenance assessment

`gbif_occurrence_facets` _tool

Facets: COUNTRY, STATE_PROVINCE, YEAR, BASIS_OF_RECORD, DATASET_KEY, KINGDOM_KEY, PHYLUM_KEY, CLASS_KEY, ORDER_KEY, FAMILY_KEY, GENUS_KEY, SPECIES_KEY, PUBLISHING_COUNTRY, MONTH, OCCURRENCE_STATUS, IUCN_RED_LIST_CATEGORY
Scope with taxonKey, country, publishingCountry, stateProvince, year, geometry, basisOfRecord, datasetKey, occurrenceStatus, or iucnRedListCategory filters — so a COUNTRY, PUBLISHING_COUNTRY, or STATE_PROVINCE bucket can be passed straight back to drill into it. country and publishingCountry take the uppercase alpha-2 form only, and a blank filter is rejected rather than dropped, both for the reasons given under gbif_search_occurrences
Aggregates sightings only by default, matching the search and count tools. To measure the presence/absence split itself, pass facet: OCCURRENCE_STATUS with occurrenceStatus: ANY
Returns one page of values ranked by count descending — up to facetLimit (max 100), the top ones only while facetOffset is 0 — with no record payloads
DATASET_KEY is the basis for splitting a result set too large for gbif_search_occurrences to page: every occurrence carries exactly one datasetKey, so its buckets sum to the scope's full total, and it has the cardinality to cut a large scope into pageable pieces. BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free too and both have a matching filter on the occurrence tools, so either can drive a further split of a bucket still over the cap — but on that scope they return 9 and 41 buckets against DATASET_KEY's 550, too coarse for the first cut. A dimension a record can lack drops that record: a 60,290,950-record scope faceted by YEAR sums to 59,407,400, leaving 883,550 undated records out, and MONTH, STATE_PROVINCE, and SPECIES_KEY behave the same way — STATE_PROVINCE included, even though the occurrence tools can filter on it
The scope filters here are narrower than gbif_search_occurrences accepts — no scientificName, month, bounding box, hasCoordinate, isInCluster, or coordinateUncertaintyInMeters. Buckets sum to a search's total only when both calls carry the same filters; re-apply the rest on each per-datasetKey search
Page past the first facetLimit with facetOffset (advance by facetLimit per page) to walk high-cardinality facets like DATASET_KEY; enrichment echoes the applied facetOffset and sets moreValuesLikely when a full page suggests more values remain
Core tool for distribution analysis ("which countries have the most records?") and trend queries ("how has observation volume changed since 2010?")

`gbif_search_datasets` _tool

Filters: free-text query, dataset type (OCCURRENCE, CHECKLIST, METADATA, SAMPLING_EVENT), publishingCountry (ISO 3166-1 alpha-2, uppercase), publishing and hosting organization UUIDs (lowercase)
publishingCountry takes the uppercase two-letter form only, for the same reason the occurrence filters do: /dataset/search matches the verbatim stored code, so gb and GBR return zero datasets where GB returns 2,416. A two-letter code GBIF does not assign (XX) is rejected upstream by name and surfaces as invalid_filter
Returns title, type, description, license, DOI, and record count. recordCount spans every occurrenceStatus, absences included — gbif_count_occurrences with the same key counts sightings only by default, so the two figures differ by design
The description is a 300-character preview — descriptionTruncated flags when it was shortened, and gbif_get_dataset returns the full text
An organization key from gbif_search_publishers chains in two ways, and they answer different questions. publishingOrg matches the organization whose data it is; hostingOrg matches the organization whose installation serves it. publishingOrg is almost always the one meant — Butterfly Conservation (0d72dd7f-6f05-46af-85c2-8b6e77ce5534) publishes 3 datasets and hosts none, while the National Biodiversity Network (07f617d0-c688-11d8-bf62-b8a03c50a862) hosts 984, those 3 among them, and publishes 1
Supplying both organization filters intersects them rather than combining them, so the same key in both fields returns only what that organization published and serves. An empty result under both is called out by name in the response notice
Both take the lowercase 8-4-4-4-12 hex UUID form and are checked before the request goes out, because GBIF answers the two silent ways of getting them wrong with a wrong result rather than an error: an empty organization value returns the whole 123,527-dataset index, and these two filters are matched case-sensitively, so an upper-cased key returns 0 where the same key lowercased matches. Both fail locally as invalid_filter, as a malformed value does
The free-text q is rejected blank on the same ground, and the route makes the case plainly: q= returns all 123,527 datasets while q= with a single space returns none. One character between the whole index and an empty page is not a distinction to leave to chance — omit the field to browse without a term
Paginated — limit up to 1000

`gbif_get_dataset` _tool

Full description, citation text (for academic reference), license, DOI
Contacts with role, name, organization, and email — capped by contactLimit (default 10, max 100); contactsTotal/contactsReturned report the full count
Temporal and geographic coverage ranges when the publisher declares them
recordCount — the indexed occurrence total, matching what gbif_search_datasets reports, for every dataset type (a CHECKLIST reports 0). It spans every occurrenceStatus, absences included; gbif_count_occurrences with the same key counts sightings only by default, so the two figures differ by design
numConstituents for aggregate datasets (e.g. iNaturalist, eBird)
Use after gbif_search_datasets or when an occurrence record's datasetKey needs provenance detail

`gbif_search_publishers` _tool

Filter by name fragment or country
country here is unconstrained on purpose: the registry endpoint matches the parsed country rather than the verbatim string, so gb, GBR, and GB all return the same 223 organizations. The uppercase-only rule the occurrence tools and gbif_search_datasets carry exists to close a silent zero that does not occur on this route. One value is rejected — an empty country, which the registry answers with all 3,561 registered organizations rather than an error; omit the field to search every country. Whitespace alone is left to the registry, which answers it with 400 Cannot parse … into a known Country, an error naming the value
q is rejected blank in both forms, because the registry drops either one and answers with all 3,561 organizations against 460 for museum; omit the field to browse without a name term
Returns organization key, title, and country. The key chains into gbif_search_datasets as publishingOrg for the datasets the organization published, or as hostingOrg for the ones its own installation serves. publishingOrg is the usual chain: of the first 25 GB organizations the registry lists, all 25 host no datasets while 13 publish one or two
Paginated — limit up to 1000

`gbif://species/{taxonKey}` _resource

Taxon record as application/json — classification, authorship, synonymy status, vernacular name, descendant count
taxonKey comes from gbif_match_species or gbif_search_species
extinct present only when explicitly flagged, absent otherwise, matching gbif_get_species
A key that resolves to no backbone taxon fails as not_found; a non-numeric key segment is rejected locally as a validation error, and a numeric one GBIF cannot parse comes back as invalid_filter

`gbif://dataset/{datasetKey}` _resource

Dataset record as application/json — title, description, citation, license, DOI, temporal and geographic coverage
Contacts fixed at 10 (no configurable limit, unlike gbif_get_dataset's contactLimit); contactsTotal/contactsReturned report the full count
recordCount spans every occurrenceStatus, absences included
datasetKey comes from gbif_search_datasets or an occurrence record's datasetKey field; a key that resolves to no dataset fails as not_found

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

GBIF-specific:

Full GBIF REST API v1 coverage: species taxonomy, occurrences, datasets, and publishers
gbif_match_species as the entry point — resolves synonyms to backbone taxon keys used throughout
Occurrence pagination guarded at GBIF's own offset+limit = 100,001 boundary — an over-cap request fails locally with a recovery hint naming the DATASET_KEY partition technique, instead of spending the retry budget on a deterministic upstream rejection, and a match larger than the cap says so on the first page rather than after hundreds of them
WKT polygon geometry support for geographic occurrence queries
Darwin Core field mapping with explicit provenance on sparse upstream fields

Agent-friendly output:

gbif_match_species is the mandatory first step — all downstream tools document which key they expect
Graceful sparse-field handling — optional fields absent from the API response are omitted rather than null-filled
Discriminated error contracts with typed reasons, structured recovery hints, and when documentation per tool

Getting started

Public Hosted Instance

A public instance is available at https://gbif-biodiversity.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "type": "streamable-http",
      "url": "https://gbif-biodiversity.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/gbif-biodiversity-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/gbif-biodiversity-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/gbif-biodiversity-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher.
No credentials — the GBIF endpoints this server calls are public.

Installation

Clone the repository:

git clone https://github.com/cyanheads/gbif-biodiversity-mcp-server.git

Navigate into the directory:

cd gbif-biodiversity-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path where the MCP server is mounted	`/mcp`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments	none
`MCP_SESSION_MODE`	HTTP session mode: `stateful`, `stateless`, or `auto` (the schema default, which resolves to `stateful`). `src/index.ts` declares `stateless`, so set this only to override that.	`stateless`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`MCP_GC_PRESSURE_INTERVAL_MS`	Opt-in Bun-only forced-GC pressure loop (ms). Try `60000` if RSS grows under sustained HTTP load.	`0` (disabled)
`LOGS_DIR`	Directory for log files (Node.js only)	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`GBIF_BASE_URL`	GBIF API base URL override	`https://api.gbif.org/v1`
`GBIF_REQUEST_TIMEOUT_MS`	HTTP request timeout in milliseconds	`10000`
`GBIF_USER_AGENT`	`User-Agent` sent on every GBIF request. GBIF asks integrators to identify themselves with a contact URL or email.	server name, version, and repository URL
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

Docker

docker build -t gbif-biodiversity-mcp-server .
docker run --rm -p 3010:3010 gbif-biodiversity-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/gbif-biodiversity-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Thirteen tools across species taxonomy, occurrences, datasets, and publishers.
`src/mcp-server/resources`	Resource definitions. Species and dataset stable-URI resources.
`src/services/gbif`	GBIF REST API service layer — client, request handling, type definitions.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Tools (13)

gbif_match_speciesgbif_bulk_match_speciesgbif_get_speciesgbif_search_speciesgbif_get_species_classificationgbif_get_species_childrengbif_search_occurrencesgbif_count_occurrences

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

GBIF_BASE_URLdefault https://api.gbif.org/v1

Base URL every GBIF API request is built from. Override to route through a proxy or a mirror of the GBIF v1 API.

GBIF_REQUEST_TIMEOUT_MSdefault 10000

Milliseconds a single GBIF API request may take before it is aborted. Aborted attempts fall to the service's retry policy.

GBIF_USER_AGENT

Sent as the User-Agent header on every GBIF API request. GBIF asks integrators to identify themselves with a contact URL or email. Unset or blank sends the server name, version, and repository URL.

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "gbif-biodiversity-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/gbif-biodiversity-mcp-server@0.7.5"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "GBIF_BASE_URL": "https://api.gbif.org/v1",
        "GBIF_REQUEST_TIMEOUT_MS": "10000",
        "GBIF_USER_AGENT": "<YOUR_GBIF_USER_AGENT>"
      }
    }
  }
}

@cyanheads/gbif-biodiversity-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

gbif_match_species

gbif_bulk_match_species

gbif_get_species

gbif_search_species

gbif_get_species_classification

gbif_get_species_children

gbif_search_occurrences

gbif_count_occurrences

gbif_get_occurrence

gbif_occurrence_facets

gbif_search_datasets

gbif_get_dataset

gbif_search_publishers

@cyanheads/gbif-biodiversity-mcp-server

Overview

Tools

Resources

Capability reference

gbif_match_species tool

gbif_bulk_match_species tool

gbif_get_species tool

gbif_search_species tool

gbif_get_species_classification tool

gbif_get_species_children tool

gbif_search_occurrences tool

gbif_count_occurrences tool

gbif_get_occurrence tool

gbif_occurrence_facets tool

gbif_search_datasets tool

gbif_get_dataset tool

gbif_search_publishers tool

gbif://species/{taxonKey} resource

gbif://dataset/{datasetKey} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`gbif_match_species` _tool

`gbif_bulk_match_species` _tool

`gbif_get_species` _tool

`gbif_search_species` _tool

`gbif_get_species_classification` _tool

`gbif_get_species_children` _tool

`gbif_search_occurrences` _tool

`gbif_count_occurrences` _tool

`gbif_get_occurrence` _tool

`gbif_occurrence_facets` _tool

`gbif_search_datasets` _tool

`gbif_get_dataset` _tool

`gbif_search_publishers` _tool

`gbif://species/{taxonKey}` _resource

`gbif://dataset/{datasetKey}` _resource