Skip to main content
Glama
tyson-swetnam

gbif-mcp

by tyson-swetnam
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Remote

gbif_occurrence_search

Read-onlyIdempotent

Search GBIF occurrence records by taxonomy, location, date, dataset, and data quality to find species observations and specimens, with paginated results and optional facet counts.

Instructions

Search GBIF occurrence records (species observations and specimens) with comprehensive filtering by taxonomy, geography, time, data quality, and more. Returns paginated results with optional facets for aggregations.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
qNoSimple full-text search parameter. The value for this parameter can be a simple word or a phrase. Wildcards are not supported.
yearNoThe 4 digit year. A year of 98 will be interpreted as AD 98. Supports range queries. Example: 1998 (single year), "2015,2020" (range from 2015 to 2020). Parameter may be repeated or a range.
depthNoDepth in metres relative to altitude. For example 10 metres below a lake surface with given altitude. Supports range queries. Example: "10,20" (between 10 and 20 meters depth). Parameter may be repeated or a range.
facetNoA facet name used to retrieve the most frequent values for a field. Facets are allowed for all search parameters except geometry and geoDistance. This parameter may be repeated to request multiple facets. Example: ["datasetKey", "basisOfRecord"] to get counts by dataset and basis of record. Note: terms not available for searching are not available for faceting.
issueNoA specific interpretation issue as defined in GBIF OccurrenceIssue enumeration. Common values: COUNTRY_COORDINATE_MISMATCH, ZERO_COORDINATE, TAXON_MATCH_FUZZY, RECORDED_DATE_INVALID, COORDINATE_OUT_OF_RANGE, etc. Use to filter by data quality issues or to exclude problematic records. Example: "COUNTRY_COORDINATE_MISMATCH". Parameter may be repeated.
limitNoControls the number of results in the page. Using too high a value will be overwritten with the maximum threshold, which is 300 for this service. Sensible defaults are used so this may be omitted. Example: limit=100 to get 100 results per page.
monthNoThe month of the year, starting with 1 for January. Supports range queries. Example: 5 (May), can also use range like "3,6" (March through June). Parameter may be repeated or a range.
decadeNoDecade, calculated as year/10. For example, 199 represents the 1990s (1990-1999). Example: 199 (1990s), 200 (2000s). Parameter may be repeated.
offsetNoDetermines the offset for the search results. A limit of 20 and offset of 40 will get the third page of 20 results. This service has a maximum offset of 100,000. Example: offset=300 to start at the 301st result.
countryNoThe 2-letter country code (as per ISO-3166-1) of the country in which the occurrence was recorded. Example: "US" (United States), "BR" (Brazil), "GB" (United Kingdom), "AF" (Afghanistan). Parameter may be repeated.
classKeyNoClass taxon key from the GBIF backbone. All child taxa are included in the search. Example: 212 (for Aves - birds). Parameter may be repeated.
genusKeyNoGenus taxon key from the GBIF backbone. All child taxa are included in the search. Example: 2435194 (for Panthera). Parameter may be repeated.
geometryNoSearches for occurrences inside a polygon described in Well Known Text (WKT) format. Only POLYGON and MULTIPOLYGON are accepted. Polygons must have anticlockwise ordering of points. Example: "POLYGON ((30.1 10.1, 40 40, 20 40, 10 20, 30.1 10.1))". Parameter may be repeated.
orderKeyNoOrder taxon key from the GBIF backbone. All child taxa are included in the search. Example: 729 (for Carnivora). Parameter may be repeated.
taxonKeyNoA taxon key from the GBIF backbone or the specified checklist. All included (child) and synonym taxa are included in the search, so a search for Aves with taxonKey=212 will match all birds, no matter which species. Example: 2476674. Parameter may be repeated.
continentNoContinent, as defined in GBIF Continent vocabulary. Values: AFRICA, ANTARCTICA, ASIA, EUROPE, NORTH_AMERICA, OCEANIA, SOUTH_AMERICA. Example: "EUROPE". Parameter may be repeated.
elevationNoElevation (altitude) in metres above sea level. Supports range queries. Example: "1000,1250" (between 1000 and 1250 meters). Parameter may be repeated or a range.
familyKeyNoFamily taxon key from the GBIF backbone. All child taxa are included in the search. Example: 9703 (for Felidae - cats). Parameter may be repeated.
mediaTypeNoThe kind of multimedia associated with an occurrence. Values: STILL_IMAGE (photos/illustrations), MOVING_IMAGE (videos), SOUND (audio recordings). Example: "STILL_IMAGE" to find occurrences with photographs. Parameter may be repeated.
phylumKeyNoPhylum taxon key from the GBIF backbone. All child taxa are included in the search. Example: 44 (for Chordata). Parameter may be repeated.
waterBodyNoThe name of the water body in which the Location occurs. Example: "Baltic Sea", "Pacific Ocean", "Lake Victoria". Parameter may be repeated.
datasetKeyNoThe occurrence dataset key (a UUID). Example: "13b70480-bd69-11dd-b15f-b8a03c50a862". Parameter may be repeated.
kingdomKeyNoKingdom taxon key from the GBIF backbone. All child taxa are included in the search. Example: 1 (for Animalia). Parameter may be repeated.
recordedByNoThe person who recorded the occurrence. Example: "Charles Darwin", "MiljoStyrelsen". Parameter may be repeated.
typeStatusNoNomenclatural type (type status, typified scientific name, publication) applied to the subject. Filters for type specimens. Example: "HOLOTYPE" (single specimen designated as the type), "PARATYPE" (additional specimens cited in the description), "SYNTYPE", "LECTOTYPE", etc. Parameter may be repeated.
repatriatedNoFilters for records whose publishing country is different from the country where the record was recorded. Example: true to find specimens collected in one country but held in another.
subgenusKeyNoSubgenus taxon key from the GBIF backbone. All child taxa are included in the search. Parameter may be repeated.
recordNumberNoAn identifier given to the occurrence at the time it was recorded. Often serves as a link between field notes and an occurrence record. Example: "OPP 7101". Parameter may be repeated.
basisOfRecordNoBasis of record, as defined in GBIF BasisOfRecord vocabulary. Values: OBSERVATION (general observation), HUMAN_OBSERVATION (visual/aural observation by human), MACHINE_OBSERVATION (automated sensor), MATERIAL_SAMPLE (physical sample), PRESERVED_SPECIMEN (museum specimen), FOSSIL_SPECIMEN (fossilized specimen), LIVING_SPECIMEN (zoo/botanical garden), MATERIAL_CITATION (specimen cited in publication), OCCURRENCE (generic type). Example: "PRESERVED_SPECIMEN". Parameter may be repeated.
catalogNumberNoAn identifier assigned by the source within a physical collection or digital dataset for the record which may not be unique, but should be fairly unique in combination with the institution and collection code. Example: "K001275042". Parameter may be repeated.
facetMincountNoUsed in combination with the facet parameter. Set facetMincount={#} to exclude facets with a count less than {#}. Example: facetMincount=10000 to only show facet values appearing 10,000+ times.
hasCoordinateNoLimits searches to occurrence records which contain a value in both latitude and longitude. Set to true to limit to records with coordinate values, false to limit to records without coordinate values. Example: true.
publishingOrgNoThe publishing organization's GBIF key (a UUID). Example: "e2e717bf-551a-4917-bdc9-4fa0f342c530". Parameter may be repeated.
stateProvinceNoThe name of the next smaller administrative region than country (state, province, canton, department, region, etc.) in which the Location occurs. This term does not have data quality checks. Example: "Leicestershire", "California", "Queensland". Parameter may be repeated.
collectionCodeNoAn identifier assigned by the source to identify the physical collection or digital dataset uniquely within the context of an institution. Example: "F" (Flora collection). Parameter may be repeated.
scientificNameNoA scientific name from the GBIF backbone or the specified checklist. All included and synonym taxa are included in the search. Under the hood a call to the species match service is done first to retrieve a taxonKey. Only unique scientific names will return results, homonyms return nothing! Consider using the taxonKey parameter instead. Example: "Quercus robur". Parameter may be repeated.
decimalLatitudeNoLatitude in decimal degrees between -90° and 90° based on WGS 84. Supports range queries. Example: "40.5,45" (between 40.5 and 45 degrees).
institutionCodeNoAn identifier assigned by the source to identify the institution the record belongs to. Not guaranteed to be unique. Example: "K" (Royal Botanic Gardens, Kew). Parameter may be repeated.
decimalLongitudeNoLongitude in decimals between -180 and 180 based on WGS 84. Supports range queries. Example: "-120,-95.5" (between -120 and -95.5 degrees).
facetMultiselectNoUsed in combination with the facet parameter. Set facetMultiselect=true to still return counts for values that are not currently filtered. Useful for implementing multi-select faceted search interfaces.
publishingCountryNoThe 2-letter country code (as per ISO-3166-1) of the country where the publishing organization is based. Example: "DK" (Denmark). Parameter may be repeated.
hasGeospatialIssueNoLimits searches to occurrence records which have spatial issues flagged (e.g., coordinates are invalid, out of range, country mismatch). Set to false to exclude records with geospatial issues, true to only include records with issues. Example: false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered without description help. The description adds that results are paginated and that facets can return aggregations, which is mild extra context, but it says nothing about rate limits, the 100k offset ceiling interaction, or result ordering — gaps the schema covers only partially.

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

Conciseness5/5

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

Two sentences, both earning their place: the first front-loads what is searched and over what dimensions, the second immediately follows with the return shape. No filler, no restatement of the tool name.

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

Completeness3/5

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

For a 42-parameter tool with no output schema, the description should carry more of the return-value burden than 'paginated results with optional facets' — it never indicates what fields come back per record or how facets are structured in the response. Annotations cover safety, but the read-result contract is left thin.

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?

With 100% schema description coverage the baseline is 3, but the description earns a bump by giving a categorical map of the 42 parameters ('taxonomy, geography, time, data quality'), which orients an agent to the filter surface faster than scanning the schema. It still adds no per-parameter syntax or format detail beyond what the schema already documents.

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

Purpose4/5

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

States a specific verb and resource ('Search GBIF occurrence records') and elaborates the record types (species observations and specimens) plus the filter dimensions. It is clear what the tool does, but it never distinguishes itself from sibling tools that also read occurrence data (gbif_occurrence_count, the numerous gbif_occurrence_counts_by_* tools, or the download family), so an agent gets no routing help.

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

Usage Guidelines3/5

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

Usage is only implied: 'comprehensive filtering ... and more' suggests this is the general-purpose query entry point, but there is no explicit when-to-use guidance, no statement of when to prefer gbif_occurrence_count or the counts_by_* aggregators, and no prerequisites or exclusions. Adequate but leaves the alternative-selection decision to inference.

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

Deploy Server

Other Tools