
gbif-biodiversity-mcp-server
io.github.cyanheads/gbif-biodiversity-mcp-server
Search GBIF species taxonomy, occurrence records, datasets, and publishers.
Documentation
@cyanheads/gbif-biodiversity-mcp-server
Search GBIF species taxonomy, occurrence records, datasets, and publishers via MCP. STDIO or Streamable HTTP.
Public Hosted Server: https://gbif-biodiversity.caseyjhand.com/mcp
Overview
Species taxonomy, occurrence records, datasets, and publishers from the Global Biodiversity Information Facility (GBIF). Match names to the backbone taxonomy, search and aggregate 3.9B+ occurrence records with Darwin Core filters, and trace records back to their datasets and publishers.
Tools
| Tool | Description |
|---|---|
gbif_match_species | Match a scientific name to the GBIF backbone or the Catalogue of Life, returning its taxon key, confidence, and classification |
gbif_bulk_match_species | Match up to 50 scientific names, each optionally narrowed to a kingdom, in one call, one result per name in input order |
gbif_get_species | Fetch a backbone taxon by key: classification, authorship, synonymy, vernacular name, descendant count |
gbif_search_species | Search or browse the backbone by name fragment, rank, or a kingdom, family, or genus name |
gbif_get_species_classification | Return a taxon's parent chain, root-first from kingdom to its immediate parent |
gbif_get_species_children | List a taxon's direct children, such as the genera in a family or the species in a genus |
gbif_search_occurrences | Search 3.9B+ occurrence records by taxon, place, date, basis of record, publishing organization, type status, establishment means, license, presence/absence, and IUCN category |
gbif_count_occurrences | Count occurrences matching a filter without fetching records |
gbif_get_occurrence | Fetch one full Darwin Core occurrence record by key |
gbif_occurrence_facets | Aggregate occurrence counts by country, year, dataset, taxon, status, and other dimensions, optionally naming taxon, dataset, publishing organization, and GADM area buckets |
gbif_search_datasets | Search datasets by keyword, type, publishing country, or publishing or hosting organization |
gbif_get_dataset | Fetch full dataset metadata by UUID: citation, contacts, license, DOI, publishing organization key, coverage |
gbif_search_publishers | Search GBIF-registered publishing organizations by name 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, publishing organization key |
Both resources are also reachable via gbif_get_species and gbif_get_dataset; many MCP clients are tool-only and never surface resources.
Skills
| Skill | Description |
|---|---|
gbif-biodiversity-guide | Agent guide: where each key comes from, which region filter selects which records, and the checks before quoting a count, a trend, or an absence. Installed with the Claude Code and Codex plugins and the .mcpb, and served over MCP at skill://gbif-biodiversity-guide/SKILL.md |
Capability reference
gbif_match_species tool
- One scientific
name(common names go togbif_search_species), with optionalstrict, akingdomto disambiguate, an expectedrank, and achecklistKey - Returns
taxonKey, the accepted taxon to pass to the occurrence tools, plusmatchedTaxonKeywhen a synonym was resolved andacceptedName(its canonical name, without authorship) whenever GBIF's answer names the accepted taxon,matchType(EXACT,FUZZY, orHIGHERRANK: a match at a higher rank, such as a misspelled species falling back to its genus or kingdom, wheretaxonKeycovers that whole taxon, or its accepted taxon when the taxon GBIF fell back to is a synonym, and anoticenames it),confidence0–100 (review below 80; aHIGHERRANKmatch can score above 90), and the classification with a key at each rank matchTypeNONEfails asno_match, carrying GBIF's note when it gives one (for several equal matches, setkingdom); a blankkingdomfails asinvalid_filterchecklistKeyis opt-in. Omitted, ord7dddbf4-2cf0-4f39-9b2a-bb099caae36c, matches the GBIF Backbone, whose integer keys the occurrence and species tools take; GBIF no longer updates it.7ddf754f-d193-4cc9-b351-99906754a03bmatches the Catalogue of Life eXtended Release, the taxonomy GBIF now maintains, where a recently described or revised name can match exactly. Its keys come back as case-sensitive strings inchecklistTaxonKey(andchecklistMatchedTaxonKeyfor a synonym) with notaxonKey,matchedTaxonKey, or rank keys. The occurrence tools take one aschecklistTaxonKeywith the samechecklistKey; the species tools, which take a numeric backbonetaxonKey, do not.statusmay then bePROVISIONALLY_ACCEPTEDandmatchTypeVARIANT. The route isGBIF_BASE_URLwith its trailing/v1replaced by/v2, so a base URL not ending in/v1fails the call as a configuration error
gbif_bulk_match_species tool
- Scientific
nameswithstrictandchecklistKey(as ongbif_match_species, applied to the whole batch); the first 50 are processed in input order. Each entry is a name string or{ name, kingdom }, where the entry'skingdomapplies to that name alone and resolves a name shared across kingdoms such as Oenanthe (a bird genus and a plant genus). A blankkingdomon any entry, the unprocessed tail included, fails the call asinvalid_filter. With read-limit clamping enabled (default), extra entries are returned inunprocessedNamesexactly as submitted, preserving order and duplicates for the next call - Each result carries
nameandmatchType, and on a matchtaxonKey,matchedTaxonKeyandacceptedName(synonyms), andconfidence; aHIGHERRANKrow carries anotenaming the higher taxon GBIF matched and what itstaxonKeycovers: that taxon, or its accepted taxon when it is a synonym. An unmatched name isNONE, with GBIF's explanation innotewhen it gives one (such as several equal matches for a name shared across kingdoms, with a pointer to resubmit the entry withkingdomwhile it has none); a failed lookup isERRORwitherrorand, when classified,reason, and neither fails the batch
gbif_get_species tool
- One backbone
taxonKey, a non-negative integer (0is the backbone kingdom incertae sedis); a key not in the backbone fails asnot_found, one past the 32-bit range asinvalid_filter, and a fraction or negative key fails at the schema - Returns the classification with rank keys,
authorship,vernacularName,numDescendants,publishedIn, andparentKey; ataxonomicStatusofSYNONYMcomes withacceptedKeyandaccepted. GBIF's taxon record carries no occurrence count: usegbif_count_occurrences
gbif_search_species tool
qname fragment (scientific and vernacular),rank,isExtinct, and a checklistdatasetKey(omit for the backbone); up to 1,000 per page with integerlimitandoffset, whereoffset + limitmay not exceed 100,000- Taxa carry the checklist usage
key, optional sourcedatasetKeyand mapped backbonenubKey,rank,taxonomicStatus, classification names,vernacularName(GBIF's own, else the first English vernacular name containingqwhenqis not part of the row's own scientific name, else the first English one), andnumDescendants.numOccurrencesappears only when GBIF supplies a positive value; its species search sends a0placeholder on every row, so count withgbif_count_occurrencesonnubKeyor aSPECIES_KEYfacet. Enrichment reportstotalCount,endOfRecords, and thetaxonScopeapplied. Occurrence queries usenubKeywhen supplied; otherwise resolve the name withgbif_match_species. OmitteddatasetKeyselects GBIF Backbone Taxonomyd7dddbf4-2cf0-4f39-9b2a-bb099caae36c kingdom,family, andgenustake names, matched exactly as GBIF capitalizes them; the narrowest one scopes, andkingdombeside a narrower one disambiguates it. An unknown name fails asunresolved_taxon_scope, a genus outside the named family asconflicting_taxon_scope, and a scope paired with a non-backbonedatasetKeymatches nothing. A blank filter or a malformeddatasetKeyfails asinvalid_filter- GBIF's species search serves nothing past an
offset + limitof 100,000, whatever the query. The sum is checked on the appliedlimitbefore any request, and a larger one fails aspagination_cap_exceeded. WhentotalCountexceeds 100,000, every page carries a notice naming the ceiling and the way past it: narrow withkingdom,family,genus,rank,isExtinct, orq, or walk a subtree withgbif_get_species_children, which has no ceiling
gbif_get_species_classification tool
- One
taxonKey; returnsclassificationroot-first from kingdom to the immediate parent, each entry withkey,rank,name, andscientificName - The queried taxon is not included (use
gbif_get_species); a root taxon returns an empty chain with a notice, an unknown key fails asnot_found, one past the 32-bit range asinvalid_filter, and a fraction or negative key fails at the schema
gbif_get_species_children tool
- One
taxonKey(a non-negative integer;0is the backbone's incertae sedis kingdom), up to 1,000 children per page with integerlimitandoffset; no filters. A fraction or negative value fails at the schema; an unknown key fails asnot_found, one past GBIF's 32-bit range asinvalid_filter - Each child carries
key,canonicalName,rank,taxonomicStatus,vernacularNamewhen GBIF has one, andnumDescendants; GBIF sends no occurrence count, so usegbif_count_occurrenceswith the child'skey. GBIF reports no total, soendOfRecords(withtruncatedwhile more remain) is the continuation signal - An empty later page gives offset-reset guidance; only an empty first page for an existing taxon means no direct children
gbif_search_occurrences tool
- Filters:
taxonKey(preferred: a key names exactly one taxon, where ascientificNameshared across kingdoms, such as Oenanthe, matches nothing;scientificNamedoes resolve synonyms),checklistKeywithchecklistTaxonKey,country,publishingCountry,stateProvince,gadmGid, adecimalLatitude/decimalLongitudebox or WKTgeometry,year,month,basisOfRecord,hasCoordinate,hasGeospatialIssue,isInCluster,coordinateUncertaintyInMeters,datasetKey,publishingOrg,catalogNumber,institutionCode,recordedBy,mediaType,typeStatus,establishmentMeans,license,occurrenceStatus,iucnRedListCategory;includeMediaadds each row's media; up to 300 per page checklistKeyselects the taxonomy a taxon key is read in. Omitted, ord7dddbf4-2cf0-4f39-9b2a-bb099caae36c, is the GBIF Backbone andtaxonKeytakes its integer keys.7ddf754f-d193-4cc9-b351-99906754a03bis the Catalogue of Life eXtended Release: scope by one of its keys withchecklistTaxonKey(such as3WSJV, the keygbif_match_speciesreturns under the samechecklistKey), which matches the taxon and every descendant, astaxonKeydoes. A key holds uppercase letters and digits only and is matched case-sensitively; a digit-only one such as8288(the genus Tringa) is not the BackbonetaxonKeyof the same spelling.checklistTaxonKeywithout the Catalogue of LifechecklistKey, andtaxonKeywith it, fail asinvalid_filterbefore any request, since GBIF answers a key from the other taxonomy with zero records or an unrelated taxon. Rows keep their BackbonetaxonKeyeither waygadmGidis an uppercase GADM GID (ESP.1_1) GBIF derives from each record's coordinates, so records without coordinates match none; take one from aGADM_LEVEL_0_GID–GADM_LEVEL_3_GIDfacet orgbif_get_occurrence'sgadmfield.catalogNumberandinstitutionCodematch the whole value case-insensitively,recordedByone collector exactly and case-sensitively (take a spelling from aRECORDED_BYfacet), andmediaTypeisStillImage,MovingImage,Sound, orInteractiveResource.taxonKey,month,limit, andoffsetare integerspublishingOrgis the UUID of the organization that published the records, across all its datasets; take one fromgbif_search_publishers, a dataset's or an occurrence record'spublishingOrganizationKey, or aPUBLISHING_ORGfacet. It is not the organization hosting the installation, and notpublishingCountrytypeStatusandestablishmentMeansare matched case-insensitively against GBIF's TypeStatus (51 concepts) and EstablishmentMeans (7) vocabularies, then sent and echoed in the concept's own spelling. A value matches its concept and every narrower one:Typecovers every kind of type,LectotypecoversIsolectotype,nativecoversnativeEndemicandnativeReintroduced,introducedcoversintroducedAssistedColonisation. A value naming no concept fails asinvalid_filterlisting themlicenseisCC0_1_0,CC_BY_4_0, orCC_BY_NC_4_0; a blank or other value fails at the schema as-32602, notinvalid_filterhasGeospatialIssue: truekeeps records GBIF flagged with a spatial issue (zero coordinates, coordinates out of range, outside the stated country);falsekeeps unflagged ones. GBIF often drops the coordinates of a flagged record, so pairfalsewithhasCoordinate: truefor records to map- All supplied spatial filters intersect: combining
geometrywith latitude or longitude ranges restricts results to their overlap decimalLatitude,decimalLongitude, andcoordinateUncertaintyInMetersare ranges written"min,max", both ends inclusive. A value without a comma is an exact match, not a range around it, and every result carries a notice saying so.coordinateUncertaintyInMetersalso takes*for one open end ("*,1000"); a bare*, padded or not, fails asinvalid_filter- Records carry
key,taxonKey,taxonomicStatus, coordinates,eventDateandeventTime,basisOfRecord,occurrenceStatus,iucnRedListCategory,datasetKey,institutionCode,catalogNumber, andissues, plus each of these where GBIF has it:acceptedTaxonKeyandacceptedScientificName(the accepted taxon behind a synonym record, the name with authorship),publishingOrganizationKey,license(the record's Creative Commons URL; thelicensefilter takes the code form),rightsHolder,recordNumber(the collector's number, notcatalogNumber),elevationanddepthin meters, andtypeStatusandestablishmentMeans(both go back unchanged to their filters).occurrenceStatusreadsDETECTEDorNOT_DETECTED, as GBIF serves it. WithincludeMedia, each row also carries every media item of its record as{ type, identifier, license, rightsHolder }in source order, whatevermediaTypeselected; it is off by default because it adds to both response surfaces. Enrichment reportstotalCount,endOfRecords, and theoccurrenceStatusapplied - Search, count and facets echo the same
scope: effective supplied biological filters, withoccurrenceStatusalways included and pagination controls excluded.ANYis echoed but omitted upstream.taxonKeyandscientificNamecombine with OR. All 11 GBIF basis-of-record values are accepted, includingFOSSIL_SPECIMEN,OBSERVATION, andUNKNOWN - Latitude, longitude and coordinate uncertainty are independent optional facts; text renders each supplied value, including zero, in decimal degrees or meters
offset + limitcaps at 100,001 and GBIF has no cursor; a deeper request fails aspagination_cap_exceeded, and a larger match is reached by partitioning on aDATASET_KEYfacet fromgbif_occurrence_facets. A rejected filter value fails asinvalid_filter
gbif_count_occurrences tool
- Accepts every biological filter listed for
gbif_search_occurrences, with the same constraints and spatial intersection.isGeoreferencedremains an alias forhasCoordinate; either alone or both equal works, conflicting values fail asinvalid_filter - Returns
count, with theoccurrenceStatusapplied in the enrichment; a count above 100,001 carries a notice naming the partition route, and a rejected filter value fails asinvalid_filter
gbif_get_occurrence tool
- One
occurrenceKeyfrom a search result, a positive integer (a non-positive or fractional key is rejected at the schema); an unknown key fails asnot_found - The full Darwin Core record:
occurrenceStatus(NOT_DETECTEDis a survey that found nothing, not a sighting; theoccurrenceStatusfilter takesABSENTorNOT_DETECTEDfor it), coordinates withelevationanddepthin meters, GADM levels 0–3 undergadm, dates witheventTime,taxonomicStatus,acceptedTaxonKeyandacceptedScientificName(the accepted taxon behind a synonym record),iucnRedListCategory, institution, collection, and catalog codes,recordedBy,identifiedBy, andrecordNumber,typeStatusandestablishmentMeans,license(the Creative Commons URL),rightsHolder, andpublishingOrganizationKey(goes intopublishingOrg),mediawith each item'srightsHolder,identifiers, andissues
gbif_occurrence_facets tool
facetis one ofCOUNTRY,STATE_PROVINCE,YEAR,MONTH,BASIS_OF_RECORD,DATASET_KEY,PUBLISHING_COUNTRY,KINGDOM_KEY,PHYLUM_KEY,CLASS_KEY,ORDER_KEY,FAMILY_KEY,GENUS_KEY,SPECIES_KEY,OCCURRENCE_STATUS,IUCN_RED_LIST_CATEGORY,GADM_LEVEL_0_GID–GADM_LEVEL_3_GID,INSTITUTION_CODE,MEDIA_TYPE,RECORDED_BY,PUBLISHING_ORG,TYPE_STATUS,ESTABLISHMENT_MEANS,LICENSE; up to 100 values per page (facetLimit, default 10), paged withfacetOffset- Accepts every biological filter listed for
gbif_search_occurrences, with the same constraints and spatial intersection. Repeat them on the facet call and each partition search to preserve the population. ReturnstotalOccurrencesandcountsranked by count; a rejected scope value fails asinvalid_filter - Each facet request fetches one extra bucket to prove continuation.
truncated,shown, andcapappear only when that bucket exists; advancefacetOffsetby the exposed page size. An exactly full final page carries no truncation flag. Empty later pages give offset-reset guidance; an empty first page distinguishes zero matching occurrences from a dimension with no data DATASET_KEYbuckets sum to the scope's full total, so it is the facet for partitioning a search too large to page;YEAR,MONTH,STATE_PROVINCE,SPECIES_KEY,INSTITUTION_CODE,MEDIA_TYPE,RECORDED_BY,TYPE_STATUS, andESTABLISHMENT_MEANSdrop records that lack the field, and the GADM levels drop records without coordinates or outside every GADM unit at that level.MEDIA_TYPEandRECORDED_BYbuckets overlap (a record with two media types or two collectors counts in each), and so doTYPE_STATUSandESTABLISHMENT_MEANS(a record counts under its concept and every broader one: anIsolectotypealso underLectotypeandType), so their sums can exceedtotalOccurrences.INSTITUTION_CODEbuckets come back lowercased andinstitutionCodetakes them unchanged;PUBLISHING_ORG,TYPE_STATUS,ESTABLISHMENT_MEANS, andLICENSEbuckets go back unchanged aspublishingOrg,typeStatus,establishmentMeans, andlicense, andGADM_LEVEL_*_GIDbuckets asgadmGid.OCCURRENCE_STATUSbuckets readDETECTEDandNOT_DETECTED, which theoccurrenceStatusfilter takes unchanged.KINGDOM_KEY–SPECIES_KEYbuckets are Backbone keys fortaxonKey, or, under the Catalogue of LifechecklistKey, Catalogue of Life keys forchecklistTaxonKey. Passfacet: OCCURRENCE_STATUSwithoccurrenceStatus: ANYfor the presence/absence splitincludeLabels: truenames each bucket on aKINGDOM_KEY–SPECIES_KEY,DATASET_KEY,PUBLISHING_ORG, orGADM_LEVEL_0_GID–GADM_LEVEL_3_GIDpage:counts[].labelis the taxon'scanonicalName, the datasettitle, the organizationtitle, or the administrative area'sname. Taxon buckets are looked up in the taxonomychecklistKeyselects, never by the shape of the key, since8288is a Catalogue of Life genus and a Backbone family. It costs one GBIF request per exposed bucket (never the lookahead), at most 8 in flight server-wide, no retries, and one 10 s deadline per page; a bucket whose lookup fails, finds no name, or misses it has nolabeland is counted innotice, which points an unlabeled GADM bucket atgbif_get_occurrence'sgadmfield. Other dimensions ignore it, and without it a facet call is one request. Labeling Catalogue of Life buckets reads the/v2route, so aGBIF_BASE_URLnot ending in/v1fails that call as a configuration error
gbif_search_datasets tool
- Filters:
q,type(OCCURRENCE,CHECKLIST,METADATA,SAMPLING_EVENT),publishingCountry,publishingOrg,hostingOrg; up to 1,000 per page, whereoffset + limitmay not exceed 125,000 - Returns
key,title,type,license,doi,recordCount,publishingOrganizationKeyandpublishingOrganizationTitle, and a 300-characterdescriptionpreview, withdescriptionTruncatedflagging a cut (gbif_get_datasethas the full text).publishingOrganizationKeygoes back in aspublishingOrg.limitandoffsetare integers publishingOrgmatches the organization whose data it is and is the usual chain fromgbif_search_publishers;hostingOrgmatches the organization whose installation serves it, and the two together intersect. Both take the lowercase UUID form; anything else, like any rejected filter value, fails asinvalid_filter- GBIF's dataset search serves nothing past an
offset + limitof 125,000. The sum is checked on the appliedlimitbefore any request, and a larger one fails aspagination_cap_exceeded. WhentotalCountexceeds 125,000, every page carries a notice naming the ceiling and the way past it:typesplits the index with no gap or overlap, since every dataset has exactly one of the four types, andq,publishingCountry,publishingOrg, andhostingOrgnarrow it further
gbif_get_dataset tool
- One
datasetKeyUUID andcontactLimit(default 10, max 100;0drops contact detail but keepscontactsTotal); a malformed key fails asinvalid_filter, an unknown one asnot_found - Returns
description,citationText,license,doi,publishingOrganizationKey(goes intogbif_search_datasetsaspublishingOrg; the detail record carries no organization name),recordCount,numConstituents,contactswithcontactsTotalandcontactsReturned,temporalCoverages, andgeographicCoverages
gbif_search_publishers tool
qname fragment andcountry(alpha-2 or alpha-3, any case); up to 1,000 per page with integerlimitandoffset- Returns organization
key,title,country, andcity; the key chains intogbif_search_datasetsaspublishingOrg - A blank
q, an emptycountry, or a country GBIF cannot parse fails asinvalid_filter
gbif://species/{taxonKey} resource
- Taxon record as
application/json: classification names,authorship,vernacularName,taxonomicStatuswithacceptedKeyandaccepted,numDescendants taxonKeyis a whole signed decimal integer within the signed 32-bit range;0is the backbone kingdom incertae sedis. The segment is URI-decoded once and surrounding whitespace is trimmed; leading+, zero padding and their percent-encoded equivalents are accepted. An unknown key fails asnot_found; malformed escapes, suffixes, fractions, exponents, hexadecimal forms, embedded whitespace and out-of-range values fail asinvalid_filterbefore a request. Use a backbone key fromgbif_match_speciesor a search result'snubKey, resolving its name when that mapping is absent
gbif://dataset/{datasetKey} resource
- The
gbif_get_datasetrecord asapplication/json, includingpublishingOrganizationKey, with contacts fixed at 10 datasetKeycomes fromgbif_search_datasetsor an occurrence record; an unknown key fails asnot_found, a malformed one asinvalid_filter
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:
- GBIF API v1 species, occurrence, dataset, organization, and GADM endpoints, plus v2 species matching for the Catalogue of Life, keyless, with an identifying
User-Agenton every request - Synonym-safe keys:
gbif_match_speciesresolves a synonym to its accepted taxon, and the occurrence tools filter on thattaxonKey - Opt-in Catalogue of Life matching:
checklistKeyon both match tools matches against the Catalogue of Life eXtended Release and returns string keys in separate fields, and the occurrence tools take them aschecklistTaxonKey, so a Catalogue of Life key never lands in a backbone integer field - Sightings by default: the search, count, and facet tools default
occurrenceStatustoPRESENT, excluding absence records. Records and facet buckets readDETECTEDandNOT_DETECTED, which the filter takes as well asPRESENTandABSENT. DatasetrecordCountspans every status, so it can exceed agbif_count_occurrencestotal for the same key - Strict country codes:
country(where a record was observed) andpublishingCountry(the publisher's country) on the occurrence tools, andpublishingCountryongbif_search_datasets, accept only uppercase ISO 3166-1 alpha-2, because other forms silently match nothing there.stateProvincematches verbatim and case-sensitively, so take values from aSTATE_PROVINCEfacet - Blank filters rejected: GBIF reads an empty parameter as no filter, so an optional filter sent blank or whitespace-only fails as
invalid_filterinstead of widening the query. The exception is a blankcountryorpublishingCountryon the occurrence tools, or a blankpublishingCountryongbif_search_datasets, which fails earlier at the uppercase pattern as-32602 invalid_arguments, as does a blank or unknownlicenseat its enum. Omit a field to leave it off
Agent-friendly output:
- Scope echo: enrichment reports
totalCount,endOfRecords, theoccurrenceStatusapplied, and the resolvedtaxonScope, with notices on empty results, over-cap totals, and ascientificName,stateProvince,gadmGid, orrecordedBythat matched nothing - Graceful partial failure:
gbif_bulk_match_speciesreturns aNONEorERRORrow per name instead of failing the batch - Typed errors:
invalid_filter,not_found,no_match,unresolved_taxon_scope,conflicting_taxon_scope, andpagination_cap_exceeded(ongbif_search_occurrences,gbif_search_species, andgbif_search_datasets), each with a recovery hint - Sparse fields omitted rather than null-filled:
extinctappears only on taxa GBIF explicitly flags - Dataset metadata preserves temporal ranges, single dates, and verbatim periods such as
1975-current; unsupported coverage entries are disclosed. An unavailable supplementary record count carriesrecordCountNoticewhile retaining metadata - Publisher descriptions retain paragraph breaks and decode numeric character references once; Markdown output renders publisher text literally
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:
{
"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.
{
"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):
{
"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:
{
"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.4 or higher (or Node.js v24+).
- 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
- Configure environment:
cp .env.example .env
# optionally set GBIF_USER_AGENT to a contact URL or email
Configuration
| Variable | Description | Default |
|---|---|---|
GBIF_BASE_URL | GBIF API base URL. Keep the trailing /v1: checklistKey on the match tools, and includeLabels on gbif_occurrence_facets under the Catalogue of Life checklistKey, call the /v2 route derived by replacing it, and fail as a configuration error without it. | https://api.gbif.org/v1 |
GBIF_CLAMP_READ_LIMITS | Clamp oversized whole-number read limits to the documented caps and disclose requested/applied values. Bulk matching processes the first 50 names and returns the remainder in unprocessedNames. Set false to advertise and enforce rejecting maxima instead. Strict boolean parsing rejects malformed values. | true |
GBIF_REQUEST_TIMEOUT_MS | Per-request HTTP timeout, in ms. | 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 |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | HTTP server port. | 3010 |
MCP_SESSION_MODE | HTTP session mode: stateless, stateful, or auto. src/index.ts declares stateless; set this to override it. | stateless |
MCP_AUTH_MODE | Authentication: none, jwt, or oauth. | none |
MCP_LOG_LEVEL | Log level (debug, info, warning, error, etc.). | info |
LOG_TOOL_FAILURE_PAYLOADS | Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted. | false |
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 |
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) and shared tool utilities. Thirteen tools across species taxonomy, occurrences, datasets, and publishers. |
src/mcp-server/resources | Resource definitions. Species and dataset resources. |
src/services/gbif | GBIF API service layer: HTTP client with retry, timeouts, and error mapping, plus raw response types. |
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/catchin tool logic - Use
ctx.logfor logging,ctx.statefor storage - Register new tools and resources in the
createApp()arrays insrc/index.ts - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
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.
@cyanheads/gbif-biodiversity-mcp-servernpm install @cyanheads/gbif-biodiversity-mcp-server@cyanheads/gbif-biodiversity-mcp-servernpm install @cyanheads/gbif-biodiversity-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.