gbif-biodiversity-mcp-server

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, DOI, and the publishing organization's key and name; the key goes back in as publishingOrg. 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

Name	Required	Description
`q`	No	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 every indexed dataset and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for.
`type`	No	Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists.
`limit`	No	Number of datasets to return (default 20, max 1000).
`offset`	No	Pagination offset.
`hostingOrg`	No	UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — distinct from 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. Supplied together the two filters are intersected, not combined.
`publishingOrg`	No	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. The organization that serves it is hostingOrg, which matches a different set. 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.
`publishingCountry`	No	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.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Datasets returned in this page.
`notice`	No	Guidance when results are empty, paging overshot, or an oversized read limit was clamped. Absent when none applies.
`offset`	No	Current pagination offset.
`datasets`	No	Matching datasets.
`totalCount`	No	Total matching datasets before pagination.
`endOfRecords`	No	True when there are no more results after this page.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedNov 1, 2026

addedInput schema / properties / limit / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

addedInput schema / properties / offset / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / offset / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / q / description

Previous 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."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 every indexed dataset and a whitespace-only one with none, and neither is the search a caller who filled the field was asking for."

addedOutput schema / properties / datasets / items / properties / publishingOrganizationKey

Added value: +{
+  "description": "UUID of the organization that published the dataset. Pass it back to gbif_search_datasets as publishingOrg for every dataset this organization published. Absent when GBIF omits it.",
+  "type": "string"
+}

addedOutput schema / properties / datasets / items / properties / publishingOrganizationTitle

Added value: +{
+  "description": "Name of the organization that published the dataset, as GBIF records it. Absent when GBIF omits it.",
+  "type": "string"
+}

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_filter`: A string filter other than publishingCountry was supplied blank or whitespace-only (a blank publishingCountry fails earlier, at its uppercase pattern, as -32602 invalid_arguments), 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."

Changed4 schema fields changedOct 24, 2026

changedInput schema / properties / hostingOrg / description

Previous 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."New value: +"UUID (8-4-4-4-12 hex, lowercase — matched case-sensitively, as publishingOrg is) of the organization whose installation serves the dataset — distinct from 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. Supplied together the two filters are intersected, not combined."

removedInput schema / properties / limit / maximum
```
Removed value: -1000
```

changedInput schema / properties / publishingOrg / description

Previous value: -"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."New value: +"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. The organization that serves it is hostingOrg, which matches a different set. 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."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when results are empty or paging overshot. Absent on successful result pages."New value: +"Guidance when results are empty, paging overshot, or an oversized read limit was clamped. Absent when none applies."

Changed6 schema fields changedAug 25, 2026

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"
-]

Changed3 schema fields changedAug 7, 2026

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."

Changed2 schema fields changedAug 6, 2026

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}$"
```

Changed1 schema field changedAug 6, 2026

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."

Changed1 schema field changedAug 6, 2026

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."

Changed2 schema fields changedJul 14, 2026

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"
+}

Changed1 schema field changedMay 30, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when results are empty or paging overshot. Absent on successful result pages.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/openWorld, so the bar is low, but the description still adds real behavior: the publishingOrg key round-trips back in as a filter, the two org filters intersect rather than union when combined, and matching is case-sensitive downward. That is non-obvious semantics an agent could not infer from the annotations.

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?

Three sentences, purpose front-loaded, no filler. The middle sentence is dense (two em-dash clarifications plus a return-field list) but every clause carries routing or semantics information; a small trim would make it easier to skim.

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, zero-required-parameter search tool with a full output schema, the description covers purpose, filter disambiguation, key provenance, and result shape. Nothing an agent needs before calling is missing, and the return-field list is a bonus rather than a necessity.

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?

Schema coverage is 100% and the schema itself is unusually rich, so the baseline is 3. The description still adds value by stating the uppercase ISO 3166-1 alpha-2 requirement, contrasting it with gbif_search_publishers' more lenient resolution, and explaining which of the two org keys a publisher search result usually maps to.

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?

Opens with a specific verb+resource and enumerates the actual filter axes (keyword, type, publishing country, publishing/hosting org), then states the return payload. It clearly separates this from gbif_get_dataset (lookup by key) and gbif_search_publishers (source of org keys), so an agent can route without opening a schema.

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?

Gives two concrete use cases ('find the source dataset behind a set of records', 'explore what data collections are available') and resolves the publishingOrg vs hostingOrg ambiguity with a routing rule pointing at gbif_search_publishers. It stops short of an explicit exclusion (e.g., when to prefer gbif_get_dataset once a key is known), so 4 rather than 5.

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 tools Inspect

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.

Search Datasets

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources