.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/gbif-biodiversity-mcp-server</h1> <p><b>Search GBIF species taxonomy, occurrence records, datasets, and publishers via MCP. STDIO or Streamable HTTP.</b> <div>13 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

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

Resources

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

• One scientific name (common names go to gbif_search_species), with optional strict, a kingdom to disambiguate, and an expected rank
• Returns taxonKey, the accepted taxon to pass to the occurrence tools, plus matchedTaxonKey when a synonym was resolved, matchType (EXACT, FUZZY, HIGHERRANK), confidence 0–100 (review below 80), and the classification with a key at each rank
• matchType NONE fails as no_match; a blank kingdom fails as invalid_filter

gbif_bulk_match_species _tool

• Scientific names with strict; the first 50 are processed in input order. With read-limit clamping enabled (default), extra names are returned in unprocessedNames, preserving order and duplicates for the next call
• Each result carries name and matchType, and on a match taxonKey, matchedTaxonKey (synonyms), and confidence; an unmatched name is NONE, a failed lookup is ERROR with error and, when classified, reason, and neither fails the batch

gbif_get_species _tool

• One backbone taxonKey; a key not in the backbone fails as not_found, one GBIF cannot parse (a fraction, or past the 32-bit range) as invalid_filter
• Returns the classification with rank keys, authorship, vernacularName, numDescendants, numOccurrences, publishedIn, and parentKey; a taxonomicStatus of SYNONYM comes with acceptedKey and accepted

gbif_search_species _tool

• q name fragment (scientific and vernacular), rank, isExtinct, and a checklist datasetKey (omit for the backbone); up to 1,000 per page with offset
• Taxa carry the checklist usage key, optional source datasetKey and mapped backbone nubKey, rank, taxonomicStatus, classification names, numOccurrences, and numDescendants; enrichment reports totalCount, endOfRecords, and the taxonScope applied. Occurrence queries use nubKey when supplied; otherwise resolve the name with gbif_match_species. Omitted datasetKey selects GBIF Backbone Taxonomy d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
• kingdom, family, and genus take names, matched exactly as GBIF capitalizes them; the narrowest one scopes, and kingdom beside a narrower one disambiguates it. An unknown name fails as unresolved_taxon_scope, a genus outside the named family as conflicting_taxon_scope, and a scope paired with a non-backbone datasetKey matches nothing. A blank filter or a malformed datasetKey fails as invalid_filter

gbif_get_species_classification _tool

• One taxonKey; returns classification root-first from kingdom to the immediate parent, each entry with key, rank, name, and scientificName
• The queried taxon is not included (use gbif_get_species); a root taxon returns an empty chain with a notice, an unknown key fails as not_found, and one GBIF cannot parse as invalid_filter

gbif_get_species_children _tool

• One taxonKey, up to 1,000 children per page with offset; no filters. An unknown key fails as not_found, one GBIF cannot parse as invalid_filter
• Each child carries key, canonicalName, rank, taxonomicStatus, vernacularName, numOccurrences, and numDescendants; GBIF reports no total, so endOfRecords (with truncated while 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; scientificName does not match synonyms), country, publishingCountry, stateProvince, a decimalLatitude/decimalLongitude box or WKT geometry, year, month, basisOfRecord, hasCoordinate, isInCluster, coordinateUncertaintyInMeters, datasetKey, occurrenceStatus, iucnRedListCategory; up to 300 per page
• All supplied spatial filters intersect: combining geometry with latitude or longitude ranges restricts results to their overlap
• Records carry key, taxonKey, taxonomicStatus, coordinates, eventDate and eventTime, basisOfRecord, occurrenceStatus, iucnRedListCategory, datasetKey, and issues; enrichment reports totalCount, endOfRecords, and the occurrenceStatus applied
• Search, count and facets echo the same scope: effective supplied biological filters, with occurrenceStatus always included and pagination controls excluded. ANY is echoed but omitted upstream. taxonKey and scientificName combine with OR. All 11 GBIF basis-of-record values are accepted, including FOSSIL_SPECIMEN, OBSERVATION, and UNKNOWN
• Latitude, longitude and coordinate uncertainty are independent optional facts; text renders each supplied value, including zero, in decimal degrees or meters
• offset + limit caps at 100,001 and GBIF has no cursor; a deeper request fails as pagination_cap_exceeded, and a larger match is reached by partitioning on a DATASET_KEY facet from gbif_occurrence_facets. A rejected filter value fails as invalid_filter

gbif_count_occurrences _tool

• Accepts every biological filter listed for gbif_search_occurrences, with the same constraints and spatial intersection. isGeoreferenced remains an alias for hasCoordinate; either alone or both equal works, conflicting values fail as invalid_filter
• Returns count, with the occurrenceStatus applied in the enrichment; a count above 100,001 carries a notice naming the partition route, and a rejected filter value fails as invalid_filter

gbif_get_occurrence _tool

• One occurrenceKey from a search result; an unknown key fails as not_found, one GBIF cannot parse as invalid_filter
• The full Darwin Core record: occurrenceStatus (ABSENT is a survey that found nothing, not a sighting), coordinates, GADM levels 0–3 under gadm, dates with eventTime, taxonomicStatus, iucnRedListCategory, institution, collection, and catalog codes, recordedBy and identifiedBy, media, identifiers, and issues

gbif_occurrence_facets _tool

• facet is one of COUNTRY, 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; up to 100 values per page (facetLimit, default 10), paged with facetOffset
• 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. Returns totalOccurrences and counts ranked by count; a rejected scope value fails as invalid_filter
• Each facet request fetches one extra bucket to prove continuation. truncated, shown, and cap appear only when that bucket exists; advance facetOffset by 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_KEY buckets sum to the scope's full total, so it is the facet for partitioning a search too large to page; YEAR, MONTH, STATE_PROVINCE, and SPECIES_KEY drop records that lack the field. Pass facet: OCCURRENCE_STATUS with occurrenceStatus: ANY for the presence/absence split

gbif_search_datasets _tool

• Filters: q, type (OCCURRENCE, CHECKLIST, METADATA, SAMPLING_EVENT), publishingCountry, publishingOrg, hostingOrg; up to 1,000 per page
• Returns key, title, type, license, doi, recordCount, and a 300-character description preview, with descriptionTruncated flagging a cut (gbif_get_dataset has the full text)
• publishingOrg matches the organization whose data it is and is the usual chain from gbif_search_publishers; hostingOrg matches 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 as invalid_filter

gbif_get_dataset _tool

• One datasetKey UUID and contactLimit (default 10, max 100; 0 drops contact detail but keeps contactsTotal); a malformed key fails as invalid_filter, an unknown one as not_found
• Returns description, citationText, license, doi, recordCount, numConstituents, contacts with contactsTotal and contactsReturned, temporalCoverages, and geographicCoverages

gbif_search_publishers _tool

• q name fragment and country (alpha-2 or alpha-3, any case); up to 1,000 per page
• Returns organization key, title, country, and city; the key chains into gbif_search_datasets as publishingOrg
• A blank q, an empty country, or a country GBIF cannot parse fails as invalid_filter

gbif://species/{taxonKey} _resource

• Taxon record as application/json: classification names, authorship, vernacularName, taxonomicStatus with acceptedKey and accepted, numDescendants
• taxonKey is a whole signed decimal integer within the signed 32-bit range. 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 as not_found; malformed escapes, suffixes, fractions, exponents, hexadecimal forms, embedded whitespace and out-of-range values fail as invalid_filter before a request. Use a backbone key from gbif_match_species or a search result's nubKey, resolving its name when that mapping is absent

gbif://dataset/{datasetKey} _resource

• The gbif_get_dataset record as application/json, with contacts fixed at 10
• datasetKey comes from gbif_search_datasets or an occurrence record; an unknown key fails as not_found, a malformed one as invalid_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, and organization endpoints, keyless, with an identifying User-Agent on every request
• Synonym-safe keys: gbif_match_species resolves a synonym to its accepted taxon, and the occurrence tools filter on that taxonKey
• Sightings by default: the search, count, and facet tools default occurrenceStatus to PRESENT, excluding absence records. Dataset recordCount spans every status, so it runs higher than a gbif_count_occurrences total for the same key
• Strict country codes: on the occurrence tools and gbif_search_datasets, country (where a record was observed) and publishingCountry (the publisher's country) accept only uppercase ISO 3166-1 alpha-2, because other forms silently match nothing there. stateProvince matches verbatim and case-sensitively, so take values from a STATE_PROVINCE facet
• Blank filters rejected: GBIF reads an empty parameter as no filter, so an optional filter sent blank or whitespace-only fails as invalid_filter instead of widening the query. Omit a field to leave it off

Agent-friendly output:

• Scope echo: enrichment reports totalCount, endOfRecords, the occurrenceStatus applied, and the resolved taxonScope, with notices on empty results, over-cap totals, and a stateProvince that matched nothing
• Graceful partial failure: gbif_bulk_match_species returns a NONE or ERROR row per name instead of failing the batch
• Typed errors: invalid_filter, not_found, no_match, unresolved_taxon_scope, conflicting_taxon_scope, and pagination_cap_exceeded, each with a recovery hint
• Sparse fields omitted rather than null-filled: extinct appears 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 carries recordCountNotice while 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.0 or higher (or Node.js v24+).
• No credentials: the GBIF endpoints this server calls are public.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd gbif-biodiversity-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# optionally set GBIF_USER_AGENT to a contact URL or email

Configuration

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

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 in src/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.