paleobiology-mcp-server: search fossil occurrences
paleobiology_search_occurrencesSearch fossil occurrences by clade-inclusive base_name or base_id, exact taxon_name, interval or max_ma/min_ma, modern geographic bounds, country, formation, environment, or collection_no. At least one filter is required. Formation matches PBDB stored names and preserves list/wildcard syntax; suffixes are not removed. Resolve uncertain taxon names with paleobiology_get_taxon. Rows carry modern lng/lat, reconstructed paleolng/paleolat, age, strata, classification, and source reference_no; keep the coordinate systems distinct. Every served page row is returned, with total matches and the offset that continues the page. When this deployment has DataCanvas enabled, a first page with additional matches stages up to 50,000 occurrences on a canvas: use paleobiology_dataframe_describe for columns, then paleobiology_dataframe_query for SQL over the staged set; the notice distinguishes complete from partial coverage. Later offsets and complete pages stage nothing and leave any supplied canvas untouched.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "paleobiology_search_occurrences"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum occurrences to return per page, up to 10000, subject to PBDB_MAX_OCCURRENCES. Every fetched page row is returned; the notice discloses a lower configured cap. Pair with offset to walk the match set. | |
| latmax | No | Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane. | |
| latmin | No | Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane. | |
| lngmax | No | Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither. | |
| lngmin | No | Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither. | |
| max_ma | No | Older age bound in millions of years ago. Alternative to interval. When paired with min_ma it must be strictly greater — max_ma is the deeper-time end of the window. | |
| min_ma | No | Younger age bound in millions of years ago. Alternative to interval. When paired with max_ma it must be strictly smaller — min_ma is the nearer-to-present end of the window. | |
| offset | No | Number of matching occurrences to skip before this page — page with limit by advancing offset. The response notice names the exact offset that reaches the next page. | |
| base_id | No | Clade-inclusive taxon filter by PBDB taxon id — the accepted_no from paleobiology_get_taxon or an occurrence row. Same clade-inclusive semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name, never both. | |
| country | No | PBDB country/continent codes, comma-separated; ! excludes a list and ^ subtracts a code, e.g. NOA,^US. | |
| interval | No | Named geologic interval bounding the age, e.g. "Cretaceous" or "Maastrichtian". Alternative to max_ma/min_ma. | |
| base_name | No | Clade-inclusive taxon filter — this taxon and all descendants, e.g. "Dinosauria". The usual choice. Supply this or base_id, never both. | |
| canvas_id | No | Canvas id from a prior call to restage onto the same workspace. Used only on a first page with matches beyond that page: replaces the prior occurrence table atomically with a bounded matching set, without appending. Later offsets and complete pages leave it untouched. Omit to start fresh. | |
| formation | No | Stored formation name or PBDB list/wildcard expression, passed unchanged; suffixes such as Formation are not removed. | |
| taxon_name | No | Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon. | |
| environment | No | Depositional environment: "marine", "terrestrial", or "freshwater" (lacustrine + fluvial). Omit for all. | |
| collection_no | No | Restrict to one collection (locality) by its PBDB collection_no — the fauna found together at that site. Take the id from a paleobiology_search_collections row to drill from a locality into its occurrences. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Applied filters and empty/past-end guidance, page continuation, ignored upstream filters, staged-set coverage, or optional staging unavailability. | |
| spilled | No | True when the first page had additional matches and the bounded matching set was written to the canvas. | |
| canvas_id | No | Canvas id holding the staged occurrence set — pass it to paleobiology_dataframe_describe for columns, then paleobiology_dataframe_query for SQL. Present only when spilled is true; complete pages and later offsets stage nothing. | |
| row_count | No | Rows staged on the canvas when spilled (at most 50,000); otherwise occurrences returned inline. Compare against totalCount for full-match coverage. | |
| table_name | No | Canvas table holding the staged occurrence set — the FROM target in paleobiology_dataframe_query SQL, and the table paleobiology_dataframe_describe reports columns for. Present only when spilled is true. | |
| totalCount | No | Total occurrences matching the filters upstream — the number this call was drawn from, which may exceed the staged set. | |
| attribution | No | CC-BY data attribution for the Paleobiology Database. | |
| occurrences | No | Every occurrence in the requested page, subject to the configured page cap. When spilled is true, the canvas holds the bounded matching set independently of this page; the notice states whether staging covers every match. |