Skip to main content
Glama

gbif-biodiversity-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Search Datasets

gbif_search_datasets
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoFree-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.
typeNoFilter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists.
limitNoNumber of datasets to return (default 20, max 1000).
offsetNoPagination offset.
hostingOrgNoUUID (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.
publishingOrgNoUUID (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.
publishingCountryNoISO 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.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
limitNoDatasets returned in this page.
noticeNoGuidance when results are empty or paging overshot. Absent on successful result pages.
offsetNoCurrent pagination offset.
datasetsNoMatching datasets.
totalCountNoTotal matching datasets before pagination.
endOfRecordsNoTrue when there are no more results after this page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "datasets",
+      "totalCount",
+      "offset",
+      "limit",
+      "endOfRecords"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `invalid_filter`: A filter was supplied blank or whitespace-only, publishingOrg or hostingOrg is not a lowercase 8-4-4-4-12 hex UUID, publishingCountry is a two-letter code GBIF does not assign, or GBIF rejected another filter value as malformed. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_filter"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "datasets",
-  "totalCount",
-  "offset",
-  "limit",
-  "endOfRecords"
-]
  2. Changed3 schema fields changed
    • changedInput schema / properties / hostingOrg / description
      Previous value: -"UUID (8-4-4-4-12 hex) of the hosting organization. From gbif_search_publishers results."New value: +"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."
    • addedInput schema / properties / publishingOrg
      Added value: +{
+  "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"
+}
    • changedInput schema / properties / q / description
      Previous value: -"Free-text search across dataset title and description."New value: +"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."
  3. Changed2 schema fields changed
    • changedInput schema / properties / publishingCountry / description
      Previous value: -"ISO 3166-1 alpha-2 country code of the publishing organization."New value: +"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."
    • addedInput schema / properties / publishingCountry / pattern
      Added value: +"^[A-Z]{2}$"
  4. Changed1 schema field changed
    • changedOutput schema / properties / datasets / items / properties / recordCount / description
      Previous value: -"Number of records in the dataset."New value: +"Occurrence records GBIF has indexed for this dataset, spanning every occurrenceStatus: absence records — surveys that looked for a taxon and did not find it — are counted alongside sightings, and on some datasets they are the overwhelming majority. For the sightings-only figure, call gbif_count_occurrences with this key; it defaults to occurrenceStatus PRESENT, so the two figures are expected to differ rather than one being wrong."
  5. Changed1 schema field changed
    • changedInput schema / properties / hostingOrg / description
      Previous value: -"UUID of the hosting organization. From gbif_search_publishers results."New value: +"UUID (8-4-4-4-12 hex) of the hosting organization. From gbif_search_publishers results."
  6. Changed2 schema fields changed
    • changedOutput schema / properties / datasets / items / properties / description / description
      Previous value: -"Brief description. May be absent."New value: +"Brief description, truncated to a 300-character preview. May be absent."
    • addedOutput schema / properties / datasets / items / properties / descriptionTruncated
      Added value: +{
+  "description": "True when the description was shortened to the 300-char preview; call gbif_get_dataset with this key for the full text. Omitted when the dataset has no description.",
+  "type": "boolean"
+}
  7. Changed1 schema field changed
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Guidance when results are empty or paging overshot. Absent on successful result pages.",
+  "type": "string"
+}
  8. First observed

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses crucial behavioral nuances: case-sensitive UUID matching, rejection of blank q values and the upstream consequences, and that the two organization filters are intersected, not combined. These details go well beyond annotations and materially affect invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense paragraph that front-loads the core purpose and then delivers usage guidance. Though lengthy, every sentence carries distinct value (purpose, filter distinction, return list, use cases). It could be split into bullet points, but it remains efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, entirely optional-parameter search tool with a rich output schema, the description comprehensively covers purpose, filters, return fields, and the non-obvious behaviors (case sensitivity, filter intersection, blank q handling). Combined with the schema and annotations, an agent has everything needed to select and call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage with exhaustive per-parameter descriptions (formats, examples, rejection rules). The description adds meta-level semantics that the schema does not: which filter answers 'whose data it is' versus 'whose installation serves it,' and the recommendation to use publishingOrg for publisher keys. This enriches meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Search') and resource ('GBIF datasets'), and enumerates the exact criteria (keyword, type, country, publishing/hosting organization). It also states what it returns (title, description, license, record count, DOI) and gives concrete use cases, differentiating it from sibling tools that search other resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit use cases are given ('find the source dataset behind a set of records, or explore what data collections are available...'). The description also routes the agent to the correct organization filter by noting that a key from gbif_search_publishers 'usually wants publishingOrg,' distinguishing it from the alternative. It does not explicitly exclude other search tools, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All gbif-biodiversity-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources