GBIF Biodiversity MCP Server

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

Tools

13 tools for working with GBIF species taxonomy, occurrence records, datasets, and publishers:

gbif_match_species

Match a scientific or common name against the GBIF backbone taxonomy.

• 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

gbif_bulk_match_species

Match up to 50 scientific names against the GBIF backbone taxonomy in a single call.

• 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 — neither sinks the rest of the batch

• strict: true requires an exact match for every name; common names are not supported (use gbif_search_species)

gbif_get_species

Fetch a complete taxon record by GBIF backbone key.

• 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

Search or browse the GBIF backbone taxonomy.

• Accepts name fragments matching scientific and vernacular names

• Filter by rank, kingdom, family, or genus to scope browsing

• isExtinct filter for extinct vs. extant taxa

• Scope to a specific checklist dataset with datasetKey (omit for the GBIF backbone)

• Paginated — limit up to 1000, use offset to walk through large groups

gbif_get_species_classification

Return the root-to-parent classification chain for a taxon as an ordered array.

• 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

List direct children of a backbone taxon.

• 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

Search 2.4B+ GBIF occurrence records with full Darwin Core filtering.

• Use taxonKey from gbif_match_species for reliable results — resolves synonyms automatically; scientificName filter does not

• Geographic filters: country (ISO 3166-1 alpha-2), bounding box (decimalLatitude/decimalLongitude ranges as "min,max"), or WKT polygon (geometry)

• 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

• Pagination capped at offset+limit ≈ 100,000 — use gbif_occurrence_facets for aggregate analysis beyond this

gbif_count_occurrences

Count occurrences matching a filter without fetching any records.

• Backed by the lightweight /occurrence/count endpoint — fast single-number response

• Supported filters: taxonKey, country, isGeoreferenced, datasetKey, year

• Use to assess result set size before deciding whether to paginate a full search

gbif_get_occurrence

Fetch a single occurrence record by GBIF occurrence key.

• 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–2, each with a stable GID and name), and source identifiers

• 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

Aggregate occurrence counts across a dimension.

• Facets: COUNTRY, YEAR, BASIS_OF_RECORD, DATASET_KEY, KINGDOM_KEY, PHYLUM_KEY, CLASS_KEY, ORDER_KEY, FAMILY_KEY, GENUS_KEY, SPECIES_KEY, PUBLISHING_COUNTRY, MONTH

• Scope with taxonKey, country, year, geometry, or basisOfRecord filters

• Returns top-N values ranked by count (up to facetLimit, max 100) — no record payloads

• 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

Search GBIF datasets by keyword, type, country, or publishing organization.

• Filters: free-text query, dataset type (OCCURRENCE, CHECKLIST, METADATA, SAMPLING_EVENT), publishing country, hosting organization UUID

• Returns title, type, description, license, DOI, and record count. The description is a 300-character preview — descriptionTruncated flags when it was shortened, and gbif_get_dataset returns the full text

• Use hostingOrg from gbif_search_publishers to scope to datasets from one organization

• Paginated — limit up to 1000

gbif_get_dataset

Fetch full dataset metadata by UUID.

• Full description, citation text (for academic reference), license, DOI

• Contacts with role, name, organization, and email

• Temporal and geographic coverage ranges when the publisher declares them

• 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

Search organizations registered with GBIF.

• Filter by name fragment or country

• Returns organization key, title, and country — sufficient to chain into gbif_search_datasets with hostingOrg

• Paginated — limit up to 1000

Related MCP server: MCP Registry Search

Resources

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Pluggable auth (none, jwt, oauth)

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

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 cap detection with paginationNote — redirects to facet aggregation before hitting the ~100,000 row limit

• 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

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.3.2 or higher.

• Optional: GBIF API key for higher rate limits.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd gbif-biodiversity-mcp-server

3. Install dependencies:

bun install

Configuration

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

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

Project 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 and pull requests 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.