io.github.cyanheads/paleobiology-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

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

@cyanheads/paleobiology-mcp-server

This MCP server provides tools to search fossil occurrences, resolve taxon fossil ranges, plot diversity through deep time, and look up the geologic time scale. It exposes functionality over STDIO or Streamable HTTP, with 7 tools and 2 resources.

🛠️ Key Features

Search fossil occurrences
Resolve taxon fossil ranges
Plot diversity through deep time
Look up the geologic time scale
MCP access via STDIO or Streamable HTTP

🚀 Use Cases

Investigate biodiversity patterns across deep time
Retrieve taxon ranges for paleontological analysis
Use the geologic time scale in data workflows

⚡ Developer Benefits

Model Context Protocol integration (MCP)
TypeScript-oriented project topics, including pbdb support
Topic coverage: fossils, paleobiology, paleontology, geologic-time, deep-time

⚠️ Limitations

Tool scope is limited to fossil occurrence search, taxon ranges, deep-time diversity plotting, and geologic time scale lookup (7 tools total).

Topics

biodiversitycyanheadsdeep-timefossilsgeologic-timemcpmodel-context-protocolpaleobiologypaleontologypbdbtypescript

Captured live from the server via tools/list.

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, and when the set outgrows that preview the matching occurrences — up to the per-call cap — stage on a DataCanvas (canvas_id + table_name, returned only then) for SQL via 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.

Parameters15

base_name	string	optional	Clade-inclusive taxon filter — this taxon and all descendants, e.g. "Dinosauria". The usual choice. Supply this or base_id, never both.
base_id	integer	optional	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.
taxon_name	string	optional	Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon.
collection_no	integer	optional	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.
interval	string	optional	Named geologic interval bounding the age, e.g. "Cretaceous" or "Maastrichtian". Alternative to max_ma/min_ma.
max_ma	number	optional	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	number	optional	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.
lngmin	number	optional	Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.
lngmax	number	optional	Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.
latmin	number	optional	Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
latmax	number	optional	Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
environment	string	optional	Depositional environment: "marine", "terrestrial", or "freshwater" (lacustrine + fluvial). Omit for all.
limit	integer	optional	Maximum occurrences to pull per page (1–500). Caps the pull (further bounded by PBDB_MAX_OCCURRENCES); broad queries stage that page on the canvas for SQL. Pair with offset to walk the whole match set.
offset	integer	optional	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.
canvas_id	string	optional	Canvas id from a prior call to re-stage onto the same workspace. Reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones. Omit to start fresh; the response returns a new id.

Raw schema

{
  "type": "object",
  "properties": {
    "base_name": {
      "description": "Clade-inclusive taxon filter — this taxon and all descendants, e.g. \"Dinosauria\". The usual choice. Supply this or base_id, never both.",
      "type": "string"
    },
    "base_id": {
      "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.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "taxon_name": {
      "description": "Exact taxon filter — only this taxon, not descendants. Use instead of base_name when you want a single taxon.",
      "type": "string"
    },
    "collection_no": {
      "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.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "interval": {
      "description": "Named geologic interval bounding the age, e.g. \"Cretaceous\" or \"Maastrichtian\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    },
    "lngmin": {
      "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "lngmax": {
      "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "latmin": {
      "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "latmax": {
      "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "environment": {
      "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all.",
      "type": "string",
      "enum": [
        "marine",
        "terrestrial",
        "freshwater"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Maximum occurrences to pull per page (1–500). Caps the pull (further bounded by PBDB_MAX_OCCURRENCES); broad queries stage that page on the canvas for SQL. Pair with offset to walk the whole match set.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "canvas_id": {
      "description": "Canvas id from a prior call to re-stage onto the same workspace. Reusing it REPLACES (overwrites) the prior occurrence table — each search restages the full result, it does not append to or accumulate across earlier ones. Omit to start fresh; the response returns a new id.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "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.

Parameters4

name	string	optional	Taxon name to resolve, e.g. "Tyrannosaurus" or "Ammonoidea". Provide this or taxon_no.
taxon_no	integer	optional	PBDB taxon id from a prior get_taxon, or accepted_no on an occurrence row. Provide this or name.
show_children	boolean	optional	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	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Taxon name to resolve, e.g. \"Tyrannosaurus\" or \"Ammonoidea\". Provide this or taxon_no.",
      "type": "string"
    },
    "taxon_no": {
      "description": "PBDB taxon id from a prior get_taxon, or accepted_no on an occurrence row. Provide this or name.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "show_children": {
      "default": false,
      "description": "When true, include a page of the immediate child taxa of this taxon (at most 200 per call — children_truncated says whether more remain).",
      "type": "boolean"
    },
    "children_offset": {
      "default": 0,
      "description": "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "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.

Parameters7

base_name	string	optional	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).
base_id	integer	optional	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).
count	string	optional	What to count per bin: "genera" (default), "species", or "families".
resolution	string	optional	Bin resolution: "period" (default, coarse), "epoch", or "age" (finest).
interval	string	optional	Named geologic interval bounding the span, e.g. "Mesozoic". Alternative to max_ma/min_ma.
max_ma	number	optional	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	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "base_name": {
      "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).",
      "type": "string"
    },
    "base_id": {
      "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).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "count": {
      "default": "genera",
      "description": "What to count per bin: \"genera\" (default), \"species\", or \"families\".",
      "type": "string",
      "enum": [
        "genera",
        "species",
        "families"
      ]
    },
    "resolution": {
      "default": "period",
      "description": "Bin resolution: \"period\" (default, coarse), \"epoch\", or \"age\" (finest).",
      "type": "string",
      "enum": [
        "period",
        "epoch",
        "age"
      ]
    },
    "interval": {
      "description": "Named geologic interval bounding the span, e.g. \"Mesozoic\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters4

name	string	optional	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.
min_ma	number	optional	Younger bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.
max_ma	number	optional	Older bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.
level	string	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "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.",
      "type": "string"
    },
    "min_ma": {
      "description": "Younger bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.",
      "type": "number",
      "minimum": 0
    },
    "max_ma": {
      "description": "Older bound of an age window (Ma); intervals overlapping [min_ma, max_ma] match.",
      "type": "number",
      "minimum": 0
    },
    "level": {
      "description": "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.",
      "type": "string",
      "enum": [
        "eon",
        "era",
        "period",
        "epoch",
        "age"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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.

Parameters14

base_name	string	optional	Clade-inclusive taxon filter — localities yielding this taxon or its descendants, e.g. "Dinosauria". Supply this or base_id, never both.
base_id	integer	optional	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.
interval	string	optional	Named geologic interval bounding the age, e.g. "Maastrichtian". Alternative to max_ma/min_ma.
max_ma	number	optional	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	number	optional	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.
lngmin	number	optional	Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.
lngmax	number	optional	Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.
latmin	number	optional	Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
latmax	number	optional	Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.
formation	string	optional	Geologic formation name to filter by, e.g. "Hell Creek".
lithology	string	optional	Lithology (rock type) to filter by, e.g. "sandstone".
environment	string	optional	Depositional environment: "marine", "terrestrial", or "freshwater" (lacustrine + fluvial). Omit for all.
limit	integer	optional	Maximum localities to return per page (1–500).
offset	integer	optional	Number of localities to skip — page with limit by advancing offset.

Raw schema

{
  "type": "object",
  "properties": {
    "base_name": {
      "description": "Clade-inclusive taxon filter — localities yielding this taxon or its descendants, e.g. \"Dinosauria\". Supply this or base_id, never both.",
      "type": "string"
    },
    "base_id": {
      "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.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "interval": {
      "description": "Named geologic interval bounding the age, e.g. \"Maastrichtian\". Alternative to max_ma/min_ma.",
      "type": "string"
    },
    "max_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    },
    "min_ma": {
      "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.",
      "type": "number",
      "minimum": 0
    },
    "lngmin": {
      "description": "Western edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmax with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "lngmax": {
      "description": "Eastern edge of the bounding box, decimal degrees (−180…180). Longitude is a closed pair — supply lngmin with it or neither.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "latmin": {
      "description": "Southern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "latmax": {
      "description": "Northern edge of the bounding box, decimal degrees (−90…90). Valid on its own — a lone latitude edge filters as a half-plane.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "formation": {
      "description": "Geologic formation name to filter by, e.g. \"Hell Creek\".",
      "type": "string"
    },
    "lithology": {
      "description": "Lithology (rock type) to filter by, e.g. \"sandstone\".",
      "type": "string"
    },
    "environment": {
      "description": "Depositional environment: \"marine\", \"terrestrial\", or \"freshwater\" (lacustrine + fluvial). Omit for all.",
      "type": "string",
      "enum": [
        "marine",
        "terrestrial",
        "freshwater"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Maximum localities to return per page (1–500).",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Number of localities to skip — page with limit by advancing offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "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 search_occurrences returned — call paleobiology_dataframe_describe first if you do not know the table or column names. SELECT only; writes and file-reading functions are rejected.

Parameters2

canvas_id	string	required	Canvas id returned by paleobiology_search_occurrences when its result spilled.
sql	string	required	A read-only SQL SELECT. Reference tables by the names paleobiology_search_occurrences / _describe returned.

Raw schema

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

paleobiology_dataframe_describe

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.

Parameters1

canvas_id

string

required

Canvas id returned by paleobiology_search_occurrences when its result spilled.

Raw schema

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

README.md18 KBView on GitHub

@cyanheads/paleobiology-mcp-server

Search fossil occurrences, resolve taxon fossil ranges, plot diversity through deep time, and look up the geologic time scale via MCP. STDIO or Streamable HTTP.

8 Tools • 2 Resources

MCP SDK TypeScript

Public Hosted Server: https://paleobiology.caseyjhand.com/mcp

Overview

Fossil biodiversity over the Paleobiology Database (PBDB), spanning roughly 540 million years. Resolve taxon fossil ranges, search fossil occurrences and collections by taxon, geologic time, and location, and plot diversity through deep time from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`paleobiology_search_occurrences`	Search fossil occurrences by taxon, geologic time, geography, and depositional environment. Every row carries both modern and paleo coordinates; broad results spill to a DataCanvas for SQL.
`paleobiology_get_taxon`	Resolve a taxon by name or `taxon_no` to its accepted name, rank, classification, and FAD/LAD range — the name-resolution gateway.
`paleobiology_get_diversity`	Compute a diversity / origination / extinction curve for a clade across geologic time.
`paleobiology_list_intervals`	Look up the geologic time scale — named intervals ↔ absolute Ma boundaries.
`paleobiology_search_collections`	Find fossil collections (localities) by area, geologic time, formation, and lithology.
`paleobiology_dataframe_query`	Run a read-only SQL `SELECT` over occurrence sets staged on a DataCanvas.
`paleobiology_dataframe_describe`	List the tables and columns staged on a DataCanvas.
`paleobiology_dataframe_drop`	Drop a single staged table to free memory before its TTL expires. Opt-in.

Resources

Resource	Description
`paleobiology://occurrence/{occurrence_no}`	One fossil occurrence with full detail — modern + paleo coordinates, classification, strata, locality.
`paleobiology://taxon/{taxon_no}`	One taxon record with its fossil range and classification.

All resource data is also reachable via tools — the resources mirror a single-record read of paleobiology_search_occurrences / paleobiology_get_taxon for clients that surface resources. Tool-only clients lose nothing.

Capability reference

`paleobiology_search_occurrences` _tool

base_name (a clade and all its descendants) or taxon_name (exact) filters the taxon; base_id filters the same clade by its resolved PBDB taxon_no instead of a name — exactly one of base_name/base_id, never both
Age by a named interval or a max_ma/min_ma range (min_ma strictly less than max_ma), plus an optional lng/lat bounding box (lngmin/lngmax both or neither; a lone latmin/latmax is valid) and environment (marine, terrestrial, freshwater); collection_no scopes to one locality. At least one filter is required
Every row carries both modern lng/lat (where the rock is today) and paleo lng/lat (where the landmass sat at deposition), plus formation, age interval, and higher classification (phylum–genus)
limit (max 500, default 100) and offset page against PBDB's true match count; the response names the exact offset for the next page
Broad results spill to a DataCanvas — canvas_id and table_name return only when the page spills; reusing a canvas_id replaces that canvas's occurrence table rather than accumulating
Typed errors: missing_filter, conflicting_taxon_filter, incomplete_bbox, inverted_ma_range — all rejected at the tool boundary before the upstream request

`paleobiology_get_taxon` _tool

Resolve by name or taxon_no (exactly one required) to accepted name, rank, higher classification, immediate parent, occurrence count, and FAD/LAD range in Ma
The returned taxon_no is the base_id accepted by paleobiology_search_occurrences, paleobiology_get_diversity, and paleobiology_search_collections
show_children pages immediate child taxa, up to 200 per call; children_truncated and children_offset say whether and where to continue
PBDB taxonomy can differ from GBIF's backbone — the accepted name may differ from the searched name
Typed errors: taxon_not_found, missing_selector

`paleobiology_get_diversity` _tool

Clade by base_name or base_id (exactly one required), bounded by a named interval or max_ma/min_ma range (min_ma strictly less than max_ma)
count enum: genera (default), species, families; resolution enum: period (default), epoch, age
Returns the full bin set inline, oldest-first, each bin carrying sampled/implied/origination/extinction/range-through counts and occurrence totals
Counts reflect sampled diversity, biased by collection effort and rock availability — not true past diversity
Typed errors: missing_filter, conflicting_taxon_filter, inverted_ma_range

`paleobiology_list_intervals` _tool

Filter by a case-insensitive name substring, a min_ma/max_ma overlap window, and/or a level (eon, era, period, epoch, age); no filters browses the full scale
Every name on the bundled ICS international-scale snapshot resolves offline; a name outside it (sub-stage/regional names like "Late Maastrichtian") costs one PBDB lookup, and the response's source field (bundled_ics / pbdb_upstream) plus snapshot_version say which answered
Each interval returns its level, Ma boundaries, parent_no, and — when resolved upstream — the originating scale name
Typed errors: interval_not_found (name matched nothing anywhere), interval_lookup_unavailable (retryable — PBDB unreachable for a non-bundled name)

`paleobiology_search_collections` _tool

Filter by base_name/base_id (mutually exclusive), a named interval or max_ma/min_ma range, a lng/lat bounding box, a formation or lithology name, and/or environment; at least one filter is required
Each locality returns modern lng/lat, age (named interval and Ma), formation/group/member, lithology, depositional environment, and co-occurring-fossils count (n_occs)
limit (max 500, default 100) and offset page results; the response discloses when localities remain
Take a collection_no into paleobiology_search_occurrences to see the fauna found at that locality
Typed errors: missing_filter, conflicting_taxon_filter, incomplete_bbox, inverted_ma_range

`paleobiology_dataframe_query` _tool

Runs a read-only SQL SELECT against occurrence sets staged on a DataCanvas by paleobiology_search_occurrences; writes and file-reading functions are rejected
Reference tables by the table_name a spilled search returned; the classification column is JSON — roll up by rank with json_extract_string(classification, '$.family') (also $.phylum, $.class, $.order, $.genus)
Output caps at the canvas row limit; truncated: true marks a trimmed result
Typed error: canvas_disabled when CANVAS_PROVIDER_TYPE is not duckdb

`paleobiology_dataframe_describe` _tool

Lists the tables staged on a canvas, each with its row count and column names/types/nullability — call before paleobiology_dataframe_query to discover identifiers
Typed error: canvas_disabled when CANVAS_PROVIDER_TYPE is not duckdb

`paleobiology_dataframe_drop` _tool

Drops one staged table by canvas_id + table_name to free memory before its TTL expires; dropping a nonexistent table returns dropped: false, not an error
Opt-in — registered only when PALEOBIOLOGY_DATAFRAME_DROP_ENABLED=true, absent from tools/list otherwise
Typed error: canvas_disabled when CANVAS_PROVIDER_TYPE is not duckdb

`paleobiology://occurrence/{occurrence_no}` _resource

Path param occurrence_no is a bare positive integer (regex-validated), from paleobiology_search_occurrences output
Returns the same full occurrence detail as the tool — accepted/identified names, age, modern + paleo coordinates, formation/strata, locality — plus a CC BY 4.0 attribution field
Typed error: occurrence_not_found

`paleobiology://taxon/{taxon_no}` _resource

Path param taxon_no is a bare positive integer (regex-validated), from paleobiology_get_taxon or an occurrence's accepted_no
Mirrors paleobiology_get_taxon's shape exactly — accepted name, rank, classification, parent, FAD/LAD range — plus a CC BY 4.0 attribution field
Typed error: taxon_not_found

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

PBDB-specific:

Type-safe client for the Paleobiology Database (PBDB) REST API, requesting vocab=pbdb so readable field names come straight from upstream instead of hand-mapped terse codes
Bundled ICS geologic time-scale snapshot — paleobiology_list_intervals resolves the international scale's named intervals ↔ absolute Ma boundaries with no network call, falling back to a PBDB lookup for sub-stage and regional names
DataCanvas spill for broad occurrence queries: an inline preview plus a staged table queryable with read-only SQL (count by interval, group by formation/country, roll up by family from the classification JSON column)
No auth, no API key — PBDB is fully open (MCP_AUTH_MODE defaults to none)

Agent-friendly output:

Two coordinate systems on every occurrence — modern lng/lat and paleo lng/lat, distinctly labeled, so an agent never plots a deep-time fossil on a modern coastline
Both temporal representations on every age — the named interval and its Ma boundaries
Provenance and honesty — every row carries its reference_no, every PBDB-backed tool and resource carries the CC BY attribution, sparse upstream fields (paleo-coords, formation, late_interval) are omitted rather than zeroed, and diversity counts are flagged as sampled

Getting started

Public Hosted Instance

A public instance is available at https://paleobiology.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "type": "streamable-http",
      "url": "https://paleobiology.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add one of the following to your MCP client configuration file. PBDB is keyless — no API key required.

With bunx:

json

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/paleobiology-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/paleobiology-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/paleobiology-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

To enable SQL over large occurrence sets, set CANVAS_PROVIDER_TYPE=duckdb (the @duckdb/node-api peer dep ships in dependencies). Without it, paleobiology_search_occurrences still returns its inline preview; the paleobiology_dataframe_* tools fail with a clear "canvas disabled" message.

Prerequisites

Bun v1.3 or higher (or Node.js v24+).
No API key — the Paleobiology Database is fully open.

Installation

Clone the repository:

git clone https://github.com/cyanheads/paleobiology-mcp-server.git

Navigate into the directory:

cd paleobiology-mcp-server

Install dependencies:

bun install

Configure environment (optional):

cp .env.example .env
# edit .env to override defaults — all vars are optional

Configuration

All variables are optional — the server runs with no configuration against the public PBDB API.

Variable	Description	Default
`PBDB_BASE_URL`	Paleobiology Database API base. Override for a mirror/proxy or pinned API version.	`https://paleobiodb.org/data1.2`
`PBDB_TIMEOUT_MS`	Per-request timeout in milliseconds. Diversity queries over large clades can be slow.	`30000`
`PBDB_MAX_OCCURRENCES`	Hard cap on rows pulled per occurrence/collection call.	`1000`
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable the DataCanvas spill path and `paleobiology_dataframe_*` tools.	`none`
`PALEOBIOLOGY_DATAFRAME_DROP_ENABLED`	Register `paleobiology_dataframe_drop`. Absent from `tools/list` when unset.	`false`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_SESSION_MODE`	HTTP session posture: `stateless`, `stateful`, or `auto`. The server declares `stateless` in `src/index.ts` — it holds no per-session state — and this variable overrides that declaration.	`stateless`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t paleobiology-mcp-server .
docker run --rm -p 3010:3010 paleobiology-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/paleobiology-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources and inits services.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources`	Resource definitions (`*.resource.ts`).
`src/services/pbdb`	Paleobiology Database HTTP client, normalization, and domain types.
`src/services/intervals`	In-memory index over the bundled ICS geologic time-scale snapshot.
`tests/`	Unit and integration tests mirroring `src/`.

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields (a missing paleo-coordinate is "unknown", not 0,0)

Data attribution

Data is from the Paleobiology Database, licensed CC BY 4.0 — credit it in downstream use.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (7)

paleobiology_search_occurrencespaleobiology_get_taxonpaleobiology_get_diversitypaleobiology_list_intervalspaleobiology_search_collectionspaleobiology_dataframe_querypaleobiology_dataframe_describe

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/paleobiology-mcp-server@0.3.7"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/paleobiology-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

paleobiology_search_occurrences

paleobiology_get_taxon

paleobiology_get_diversity

paleobiology_list_intervals

paleobiology_search_collections

paleobiology_dataframe_query

paleobiology_dataframe_describe

@cyanheads/paleobiology-mcp-server

Overview

Tools

Resources

Capability reference

paleobiology_search_occurrences tool

paleobiology_get_taxon tool

paleobiology_get_diversity tool

paleobiology_list_intervals tool

paleobiology_search_collections tool

paleobiology_dataframe_query tool

paleobiology_dataframe_describe tool

paleobiology_dataframe_drop tool

paleobiology://occurrence/{occurrence_no} resource

paleobiology://taxon/{taxon_no} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Data attribution

Contributing

License

Install

Configuration

Related servers

`paleobiology_search_occurrences` _tool

`paleobiology_get_taxon` _tool

`paleobiology_get_diversity` _tool

`paleobiology_list_intervals` _tool

`paleobiology_search_collections` _tool

`paleobiology_dataframe_query` _tool

`paleobiology_dataframe_describe` _tool

`paleobiology_dataframe_drop` _tool

`paleobiology://occurrence/{occurrence_no}` _resource

`paleobiology://taxon/{taxon_no}` _resource