Paleobiology Mcp Server

Working · 2.2 s

io.github.cyanheads/paleobiology-mcp-serverv0.4.0

Search fossil occurrences, taxon ranges, diversity through deep time, and the geologic time scale.

Health & Science

Source Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://paleobiology.caseyjhand.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

paleobiology_dataframe_describe Read-only

List the tables and their columns staged on a DataCanvas by paleobiology_search_occurrences. Call this before paleobiology_dataframe_query to discover the exact table_name and column names to reference in SQL.

canvas_idstring, required

Canvas id returned by paleobiology_search_occurrences when its result spilled.

Tools (8)

paleobiology_dataframe_describe

read-only

Argument	Type	Description
canvas_id*	string	Canvas id returned by paleobiology_search_occurrences when its result spilled.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "canvas_id"
  ],
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas id returned by paleobiology_search_occurrences when its result spilled."
    }
  },
  "additionalProperties": false
}

paleobiology_dataframe_query

Run a read-only SQL SELECT against occurrence result sets staged on a DataCanvas by paleobiology_search_occurrences. This is how you analyze a large fossil set without re-fetching it: count occurrences by early_interval, group by formation, country (cc), or accepted_name, or filter by a paleo/modern coordinate range. The classification column is JSON — roll up by rank with json_extract_string(classification, '$.family') (also $.phylum, $.class, $.order, $.genus). Staged rows are occurrences, so collection-only fields such as lithology are not present. Reference tables by the table_name that paleobiology_search_occurrences returned — call paleobiology_dataframe_describe first if you do not know the table or column names. A result too large to return inline comes back as its first rows, with a notice naming the ORDER BY … LIMIT/OFFSET that reads the rest. SELECT only; writes and file-reading functions are rejected.

read-only

Argument	Type	Description
sql*	string	A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned.
canvas_id*	string	Canvas id returned by paleobiology_search_occurrences when its result spilled.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "canvas_id",
    "sql"
  ],
  "properties": {
    "sql": {
      "type": "string",
      "description": "A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / paleobiology_dataframe_describe returned."
    },
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas id returned by paleobiology_search_occurrences when its result spilled."
    }
  },
  "additionalProperties": false
}

paleobiology_get_diversity

Compute a diversity / origination / extinction curve for a clade across geologic time, binned by period, epoch, or age — answers "plot dinosaur genus diversity across the Mesozoic." Pass a clade-inclusive base_name (or base_id, the same clade by resolved taxon id — exactly one of the two) and bound the span by a named interval (e.g. "Mesozoic") or a max_ma/min_ma range; choose what to count (genera, species, or families) and the bin resolution. The full bin set returns inline — a diversity series is a bounded set of geologic intervals — so you read the curve, the turnover, and the per-bin origination/extinction directly. Counts reflect SAMPLED diversity, biased by collection effort and rock availability, not true past diversity.

read-only

Argument	Type	Description
count	string	What to count per bin: "genera" (default), "species", or "families".
max_ma	number	Older bound of the span 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 span.
min_ma	number	Younger bound of the span 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 span.
base_id	integer	Clade-inclusive taxon to count, by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on an occurrence row. Same semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name (exactly one is required, never both).

paleobiology_get_references

Resolve PBDB reference_no values — the source publication on every paleobiology_search_occurrences and paleobiology_search_collections row — to full citations with authors, year, title, publication, volume, pages, and DOI. Pass the ids from a page of rows in one call: the first 25 distinct ids are resolved and any beyond that come back in remaining_reference_nos for a follow-up call. Ids PBDB has no reference for are listed in not_found. Results keep the order the ids were given.

read-only

Argument	Type	Description
reference_nos*	array	PBDB reference ids to resolve, from the reference_no field of paleobiology_search_occurrences or paleobiology_search_collections rows. Repeats are resolved once. Up to 500 accepted; the first 25 distinct ids are resolved per call.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "reference_nos"
  ],
  "properties": {
    "reference_nos": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "description": "A reference_no from an occurrence or collection row.",
        "exclusiveMinimum": 0
      },
      "maxItems": 500,
      "minItems": 1,
      "description": "PBDB reference ids to resolve, from the reference_no field of paleobiology_search_occurrences or paleobiology_search_collections rows. Repeats are resolved once. Up to 500 accepted; the first 25 distinct ids are resolved per call."
    }
  },
  "additionalProperties": false
}

paleobiology_get_taxon

Resolve a taxon by name (e.g. "Tyrannosaurus") or by integer taxon_no to its accepted name, rank, higher classification, immediate parent, fossil occurrence count, and first/last appearance (FAD/LAD) range in millions of years — "when did this clade exist, and what is it." Run this first to resolve a name into the accepted name and taxon_no, then pass that id as base_id to paleobiology_search_occurrences, paleobiology_get_diversity, or paleobiology_search_collections for a clade-inclusive filter that carries no name ambiguity (the same id also appears as accepted_no on occurrence rows). Set show_children to also list immediate child taxa. PBDB taxonomy is opinionated and can differ from GBIF's backbone, so the accepted name may differ from the name you searched.

read-only

Argument	Type	Description
name	string	Taxon name to resolve, e.g. "Tyrannosaurus" or "Ammonoidea". Provide this or taxon_no.
taxon_no	integer	PBDB taxon id from a prior get_taxon, or accepted_no on an occurrence row. Provide this or name, never both.
show_children	boolean	When true, include a page of the immediate child taxa of this taxon (at most 200 per call — children_truncated says whether more remain).
children_offset	integer	Number of immediate children to skip before the returned page — used only when show_children is true. Advance it by 200 while children_truncated is true to walk the whole child list.

Input schema (JSON)

paleobiology_list_intervals

Look up the geologic time scale — eons, eras, periods, epochs, and ages with their absolute-age boundaries in millions of years (Ma) and nesting. This is the reference that grounds every temporal filter on the other tools and translates a named interval like "Late Cretaceous" to its 100.5–66.0 Ma boundaries (and back). Filter by a name substring, a Ma range (overlap match), and/or a level; call with no filters to browse the full scale. Browsing and every name on the bundled ICS international-scale snapshot are answered offline. A name the snapshot does not carry — the sub-stage and regional names that occurrence and collection rows report, such as "Late Maastrichtian" or "Lancian" — costs one PBDB lookup across its other time scales; the response names which source answered and which scale the interval belongs to.

read-only

Argument	Type	Description
name	string	Case-insensitive substring of the interval name, e.g. "cretaceous" or "Jurassic". A name the bundled international scale does not carry is matched exactly against PBDB's other time scales.
level	string	Restrict to one rank of the international scale: eon, era, period, epoch, or age (finest). Browsing is bounded to that scale, so the sub-stage and regional ranks are not selectable here.
max_ma	number	Older bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match. When paired with min_ma it must be greater than or equal to it — equal bounds name a single point in time.
min_ma	number	Younger bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.

paleobiology_search_collections

Find fossil collections (localities) by area and geologic time — "what has been dug up here, and from what rock." Each locality returns its location, age (named interval and Ma), formation and strata, lithology, depositional environment, and the count of co-occurring fossils. Filter by a clade-inclusive base_name (or base_id, the same clade by resolved taxon id), a named interval or max_ma/min_ma range, a lng/lat bounding box, a formation or lithology name, and/or an environment. Results page inline via limit/offset (the response discloses when more remain). Take a collection_no from a row and pass it — or the same bbox+interval — to paleobiology_search_occurrences to see the actual fauna found together.

read-only

Argument	Type	Description
limit	integer	Maximum localities to return per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues.
latmax	number	Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
latmin	number	Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
lngmax	number	Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.

paleobiology_search_occurrences

Search fossil occurrences filtered by taxon, geologic time, geography, and depositional environment — the flagship. Use base_name for a clade and all its descendants (what "Tyrannosaurus occurrences" usually means), base_id for that same clade by resolved taxon id, or taxon_name for an exact taxon. Bound the age by a named interval (e.g. "Maastrichtian") or a max_ma/min_ma range, and/or a lng/lat bounding box; scope to a single locality with collection_no (take it from a paleobiology_search_collections row). At least one filter is required — taxon, time, place, environment, or collection_no. Every row carries two distinct coordinate systems — modern lng/lat (where the rock is today) and paleo lng/lat (where the landmass sat at deposition) — plus the formation, age interval, and higher classification (phylum through genus); never plot a deep-time occurrence on a modern coastline. Resolve a name with paleobiology_get_taxon first if unsure. Broad queries return many rows: an inline preview answers the immediate question. When this deployment has DataCanvas enabled, a set that outgrows the inline preview stages on a canvas (canvas_id + table_name, returned only then): list its columns with paleobiology_dataframe_describe, then run SQL with paleobiology_dataframe_query (count by interval, group by formation/country, map by region). The response reports how many occurrences matched in total, which rows this page covers, and the offset that reaches the next page — page through the whole match set with limit/offset.

read-only

Argument	Type	Description
limit	integer	Maximum occurrences to pull per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues. Pair with offset to walk the whole match set.
latmax

{ "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "count": { "enum": [ "genera", "species", "families" ], "type": "string", "default": "genera", "description": "What to count per bin: \"genera\" (default), \"species\", or \"families\"." }, "max_ma": { "type": "number", "minimum": 0, "description": "Older bound of the span 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 span." }, "min_ma": { "type": "number", "minimum": 0, "description": "Younger bound of the span 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 span." }, "base_id": { "type": "integer", "maximum": 9007199254740991, "description": "Clade-inclusive taxon to count, by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on an occurrence row. Same semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name (exactly one is required, never both).", "exclusiveMinimum": 0 }, "interval": { "type": "string", "description": "Named geologic interval bounding the span, e.g. \"Mesozoic\". Alternative to max_ma/min_ma." }, "base_name": { "type": "string", "description": "Clade-inclusive taxon to count, e.g. \"Dinosauria\" or \"Ammonoidea\" — this taxon and all descendants. Supply this or base_id (exactly one is required, never both)." }, "resolution": { "enum": [ "period", "epoch", "age" ], "type": "string", "default": "period", "description": "Bin resolution: \"period\" (default, coarse), \"epoch\", or \"age\" (finest)." } }, "additionalProperties": false }

{ "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "limit": { "type": "integer", "default": 100, "maximum": 10000, "minimum": 1, "description": "Maximum localities to return per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues." }, "latmax": { "type": "number", "maximum": 90, "minimum": -90, "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane." }, "latmin": { "type": "number", "maximum": 90, "minimum": -90, "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane." }, "lngmax": { "type": "number", "maximum": 180, "minimum": -180, "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither." }, "lngmin": { "type": "number", "maximum": 180, "minimum": -180, "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither." }, "max_ma": { "type": "number", "minimum": 0, "description": "Older age bound in millions of years ago. When paired with min_ma it must be strictly greater — max_ma is the deeper-time end of the window." }, "min_ma": { "type": "number", "minimum": 0, "description": "Younger age bound in millions of years ago. When paired with max_ma it must be strictly smaller — min_ma is the nearer-to-present end of the window." }, "offset": { "type": "integer", "default": 0, "maximum": 9007199254740991, "minimum": 0, "description": "Number of localities to skip — page with limit by advancing offset." }, "base_id": { "type": "integer", "maximum": 9007199254740991, "description": "Clade-inclusive taxon filter by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on an occurrence row. Same semantics as base_name, but unambiguous where a name is not (homonyms, synonyms, unresolved spellings). Supply this or base_name, never both.", "exclusiveMinimum": 0 }, "interval": { "type": "string", "description": "Named geologic interval bounding the age, e.g. \"Maastrichtian\". Alternative to max_ma/min_ma." }, "base_name": { "type": "string", "description": "Clade-inclusive taxon filter — localities yielding this taxon or its descendants, e.g. \"Dinosauria\". Supply this or base_id, never both." }, "formation": { "type": "string", "description": "Geologic formation name to filter by, e.g. \"Hell Creek\"." }, "lithology": { "type": "string", "description": "Lithology (rock type) to filter by, e.g. \"sandstone\"." }, "environment": { "enum": [ "marine", "terrestrial", "freshwater" ], "type": "string", "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all." } }, "additionalProperties": false }

{ "type": "object", "$schema": "https://json-schema.org/draft/2020-12/schema", "properties": { "limit": { "type": "integer", "default": 100, "maximum": 10000, "minimum": 1, "description": "Maximum occurrences to pull per page. Up to 500 are pulled per call; a larger value is served at 500, and the paging notice names that cap when more matches remain. A page can show fewer rows than it pulled when more would exceed the inline response size — the notice then names the offset that continues. Pair with offset to walk the whole match set." }, "latmax": { "type": "number", "maximum": 90, "minimum": -90, "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane." }, "latmin": { "type": "number", "maximum": 90, "minimum": -90, "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane." }, "lngmax": { "type": "number", "maximum": 180, "minimum": -180, "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither." }, "lngmin": { "type": "number", "maximum": 180, "minimum": -180, "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither." }, "max_ma": { "type": "number", "minimum": 0, "description": "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": { "type": "number", "minimum": 0, "description": "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": { "type": "integer", "default": 0, "maximum": 9007199254740991, "minimum": 0, "description": "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": { "type": "integer", "maximum": 9007199254740991, "description": "Clade-inclusive taxon filter by PBDB taxon id — the taxon_no from paleobiology_get_taxon, or accepted_no on 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.", "exclusiveMinimum": 0 }, "interval": { "type": "string", "description": "Named geologic interval bounding the age, e.g. \"Cretaceous\" or \"Maastrichtian\". Alternative to max_ma/min_ma." }, "base_name": { "type": "string", "description": "Clade-inclusive taxon filter — this taxon and all descendants, e.g. \"Dinosauria\". The usual choice. Supply this or base_id, never both." }, "canvas_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{10}$", "description": "Canvas id from a prior call to re-stage onto the same workspace. Used only when this page spills: reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones — while a page that fits inline leaves that canvas untouched. Omit to start fresh; a spilled response returns a new id." }, "taxon_name": { "type": "string", "description": "Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon." }, "environment": { "enum": [ "marine", "terrestrial", "freshwater" ], "type": "string", "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all." }, "collection_no": { "type": "integer", "maximum": 9007199254740991, "description": "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.", "exclusiveMinimum": 0 } }, "additionalProperties": false }