gbif-biodiversity-mcp-server

Get Occurrence Record

gbif_get_occurrence

Read-onlyIdempotent

Fetch a single occurrence record by its GBIF occurrence key. Returns the complete Darwin Core record — all coordinates, administrative geography (GADM levels 0–3), dates, collections metadata, collector identifiers, conservation status, media links, and quality issue flags. Check occurrenceStatus before reading the record as a sighting: ABSENT means a survey looked for the taxon and did not find it. Use the occurrence key from gbif_search_occurrences results.

Input Schema

Name	Required	Description	Default
`occurrenceKey`	Yes	GBIF occurrence key from gbif_search_occurrences results.

Output Schema

Name	Required	Description
`day`	No	Observation day. May be absent.
`key`	No	GBIF occurrence key.
`sex`	No	Sex of the individual(s). May be absent.
`gadm`	No	GADM administrative geography — stable GIDs and names at levels 0–3. May be absent.
`year`	No	Observation year. May be absent.
`class`	No	Class classification. May be absent.
`error`	No	Present when the call failed. Absent on success.
`genus`	No	Genus classification.
`media`	No	Associated media (images, audio, video). May be absent.
`month`	No	Observation month (1–12). May be absent.
`order`	No	Order classification.
`family`	No	Family classification.
`issues`	No	GBIF data quality issue flags.
`phylum`	No	Phylum classification.
`country`	No	Country name. May be absent.
`kingdom`	No	Kingdom classification.
`species`	No	Species canonical name.
`classKey`	No	Backbone taxon key for the class. May be absent.
`locality`	No	Locality description. May be absent.
`taxonKey`	No	Backbone taxon key.
`continent`	No	Continent name. May be absent.
`eventDate`	No	Observation date as ISO 8601 string. May be absent.
`eventTime`	No	Time of day of the observation, with seconds and UTC offset (e.g. 20:15:00+01:00) — the offset eventDate omits when it carries a local time. May be absent.
`lifeStage`	No	Life stage of the individual(s). May be absent.
`taxonRank`	No	Taxonomic rank of the identified taxon.
`datasetKey`	No	UUID of the source dataset.
`recordedBy`	No	Collector name(s). May be absent.
`countryCode`	No	ISO 3166-1 alpha-2 country code. May be absent.
`identifiers`	No	Alternative record identifiers from the source. May be absent.
`identifiedBy`	No	Identifier name(s). May be absent.
`occurrenceID`	No	Darwin Core occurrenceID — the source record identifier, often a URL back to the origin record. May be absent.
`basisOfRecord`	No	How the occurrence was recorded.
`canonicalName`	No	Canonical name without authorship.
`catalogNumber`	No	Catalog number within the collection. May be absent.
`stateProvince`	No	State or province. May be absent.
`collectionCode`	No	Collection code within the institution. May be absent.
`scientificName`	No	Scientific name from occurrence record.
`decimalLatitude`	No	Latitude in decimal degrees (WGS84). May be absent.
`individualCount`	No	Number of individuals. May be absent.
`institutionCode`	No	Code of the contributing institution. May be absent.
`taxonomicStatus`	No	Status of the identification carried on this record — ACCEPTED, PROVISIONALLY_ACCEPTED, SYNONYM, DOUBTFUL, and so on. Says whether the occurrence was filed under an accepted name or a synonym. May be absent.
`decimalLongitude`	No	Longitude in decimal degrees (WGS84). May be absent.
`occurrenceStatus`	No	PRESENT when the record asserts the taxon was there, ABSENT when it documents a survey that looked and did not find it. An ABSENT record is not a sighting — it carries coordinates, a date, and a recorder all the same. May be absent.
`publishingCountry`	No	Country code of the publishing organization.
`iucnRedListCategory`	No	IUCN Red List category of the taxon — CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. May be absent.
`coordinateUncertaintyInMeters`	No	Coordinate uncertainty radius in meters. May be absent.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedNov 1, 2026

addedInput schema / properties / occurrenceKey / exclusiveMinimum
```
Added value: +0
```
addedInput schema / properties / occurrenceKey / maximum
```
Added value: +9007199254740991
```
changedInput schema / properties / occurrenceKey / type
```
Previous value: -"number"New value: +"integer"
```

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The occurrenceKey does not exist in GBIF. `invalid_filter`: GBIF rejected the occurrenceKey as unparseable — a fraction, or a value past the largest integer the endpoint accepts. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The occurrenceKey does not exist in GBIF. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples
```
Previous value: -[
-  "not_found",
-  "invalid_filter"
-]New value: +[
+  "not_found"
+]
```

changedOutput schema / properties / gadm / properties / level0 / properties / gid / description

Previous value: -"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent."New value: +"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). Pass it as gadmGid to gbif_search_occurrences, gbif_count_occurrences, or gbif_occurrence_facets to filter on this unit. May be absent."

changedOutput schema / properties / gadm / properties / level1 / properties / gid / description

Previous value: -"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent."New value: +"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). Pass it as gadmGid to gbif_search_occurrences, gbif_count_occurrences, or gbif_occurrence_facets to filter on this unit. May be absent."

changedOutput schema / properties / gadm / properties / level2 / properties / gid / description

Previous value: -"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent."New value: +"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). Pass it as gadmGid to gbif_search_occurrences, gbif_count_occurrences, or gbif_occurrence_facets to filter on this unit. May be absent."

changedOutput schema / properties / gadm / properties / level3 / properties / gid / description

Previous value: -"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent."New value: +"GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). Pass it as gadmGid to gbif_search_occurrences, gbif_count_occurrences, or gbif_occurrence_facets to filter on this unit. May be absent."

Changed5 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": [
+      "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: `not_found`: The occurrenceKey does not exist in GBIF. `invalid_filter`: GBIF rejected the occurrenceKey as unparseable — a fraction, or a value past the largest integer the endpoint accepts. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "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"
+}

Changed6 schema fields changedAug 6, 2026

addedOutput schema / properties / eventTime

Added value: +{
+  "description": "Time of day of the observation, with seconds and UTC offset (e.g. 20:15:00+01:00) — the offset eventDate omits when it carries a local time. May be absent.",
+  "type": "string"
+}

changedOutput schema / properties / gadm / description

Previous value: -"GADM administrative geography — stable GIDs and names at levels 0–2. May be absent."New value: +"GADM administrative geography — stable GIDs and names at levels 0–3. May be absent."

addedOutput schema / properties / gadm / properties / level3

Added value: +{
+  "additionalProperties": false,
+  "description": "GADM level 3 — municipality/ward, the finest level GBIF indexes. Absent where the country does not subdivide that far.",
+  "properties": {
+    "gid": {
+      "description": "GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.",
+      "type": "string"
+    },
+    "name": {
+      "description": "Administrative-unit name. May be absent.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / iucnRedListCategory

Added value: +{
+  "description": "IUCN Red List category of the taxon — CR Critically Endangered, EN Endangered, VU Vulnerable, NT Near Threatened, LC Least Concern, DD Data Deficient, EX Extinct, EW Extinct in the Wild, CD Conservation Dependent. May be absent.",
+  "type": "string"
+}

addedOutput schema / properties / occurrenceStatus

Added value: +{
+  "description": "PRESENT when the record asserts the taxon was there, ABSENT when it documents a survey that looked and did not find it. An ABSENT record is not a sighting — it carries coordinates, a date, and a recorder all the same. May be absent.",
+  "type": "string"
+}

addedOutput schema / properties / taxonomicStatus

Added value: +{
+  "description": "Status of the identification carried on this record — ACCEPTED, PROVISIONALLY_ACCEPTED, SYNONYM, DOUBTFUL, and so on. Says whether the occurrence was filed under an accepted name or a synonym. May be absent.",
+  "type": "string"
+}

Changed5 schema fields changedJul 13, 2026

addedOutput schema / properties / class

Added value: +{
+  "description": "Class classification. May be absent.",
+  "type": "string"
+}

addedOutput schema / properties / classKey

Added value: +{
+  "description": "Backbone taxon key for the class. May be absent.",
+  "type": "number"
+}

addedOutput schema / properties / gadm

Added value: +{
+  "additionalProperties": false,
+  "description": "GADM administrative geography — stable GIDs and names at levels 0–2. May be absent.",
+  "properties": {
+    "level0": {
+      "additionalProperties": false,
+      "description": "GADM level 0 — country. May be absent.",
+      "properties": {
+        "gid": {
+          "description": "GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Administrative-unit name. May be absent.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "level1": {
+      "additionalProperties": false,
+      "description": "GADM level 1 — state/province. May be absent.",
+      "properties": {
+        "gid": {
+          "description": "GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Administrative-unit name. May be absent.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "level2": {
+      "additionalProperties": false,
+      "description": "GADM level 2 — county/district. May be absent.",
+      "properties": {
+        "gid": {
+          "description": "GADM GID — stable administrative-unit identifier (e.g. SWE, SWE.2_1). May be absent.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Administrative-unit name. May be absent.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / identifiers

Added value: +{
+  "description": "Alternative record identifiers from the source. May be absent.",
+  "items": {
+    "additionalProperties": false,
+    "description": "An alternative identifier for the occurrence record.",
+    "properties": {
+      "identifier": {
+        "description": "The identifier value. May be absent.",
+        "type": "string"
+      },
+      "type": {
+        "description": "Identifier type (e.g. URL, DOI, GBIF_PORTAL). May be absent.",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / occurrenceID

Added value: +{
+  "description": "Darwin Core occurrenceID — the source record identifier, often a URL back to the origin record. May be absent.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuine domain context beyond that: the scope of the returned Darwin Core record and the important semantic caveat that ABSENT occurrenceStatus means a survey searched and found nothing — a subtle trap an agent would otherwise fall into.

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?

Four sentences, front-loaded with the action and key source, then return scope, then the caveat. The field enumeration is somewhat redundant given an output schema exists, but it usefully sets expectations about record breadth and costs only one sentence.

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 single-parameter, read-only lookup with an output schema and full annotations, nothing an agent needs is missing: what it does, where the key comes from, what comes back, and the one interpretive pitfall (occurrenceStatus ABSENT).

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

Parameters3/5

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

Schema coverage is 100% and the sole parameter's schema description already says the key comes from gbif_search_occurrences results, so the description largely restates it. Baseline 3 applies; no additional format, range, or validation detail is contributed.

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?

States a specific verb and resource ("Fetch a single occurrence record by its GBIF occurrence key") and implicitly distinguishes itself from the list-producing siblings gbif_search_occurrences and gbif_count_occurrences. An agent can immediately tell this is the single-record retrieval tool.

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?

Explicitly routes the agent: "Use the occurrence key from gbif_search_occurrences results," which establishes the correct call sequence. It also gives a domain caution (check occurrenceStatus before reading as a sighting), but does not state when this tool should not be used versus alternatives like gbif_occurrence_facets.

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.