@cyanheads/paleobiology-mcp-server

Tools

Eight tools (seven by default) — five domain tools for the Paleobiology Database, plus a DataCanvas trio for SQL over staged occurrence sets. Large occurrence results spill to a canvas; the other domain tools return inline.

paleobiology_search_occurrences

Search fossil occurrences filtered by taxon, geologic time, geography, and environment — the flagship.

• base_name (a clade and all its descendants) or taxon_name (exact) for the taxon filter

• base_id filters the same clade by its resolved PBDB taxon_no — take it from paleobiology_get_taxon (or accepted_no on an occurrence row) and skip the name ambiguity. base_name and base_id are mutually exclusive; sending both is rejected at the tool boundary

• Age by a named interval (e.g. Maastrichtian) or a max_ma/min_ma range, and/or a lng/lat bounding box

• collection_no scopes the search to a single locality — drill from a paleobiology_search_collections row into the fauna found there

• environment enum: marine, terrestrial, freshwater

• At least one filter (taxon, time, place, environment, or collection_no) is required — an unfiltered call is rejected before the upstream request, not reported as PBDB being unavailable

• lngmin/lngmax are a closed pair (both or neither), and min_ma must be strictly less than max_ma — both are rejected at the tool boundary with a recovery hint, before the upstream request. A lone latmin or latmax is valid and filters as a half-plane

• 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 formation, age interval, and higher classification (phylum through genus)

• 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 (limit, further bounded by PBDB_MAX_OCCURRENCES) — stage on a DataCanvas for SQL via paleobiology_dataframe_query. canvas_id and table_name come back only on that spill path; a result that fits inline stages nothing

• Results page inline via limit/offset against the true upstream match count. When occurrences remain, the notice names the page bounds and the exact next offset (Showing occurrences 1–500 of 4170. Advance offset to 500 for the next page.); paging past the end reports the overshoot instead of blaming the filters

• Reusing a canvas_id replaces that canvas's occurrence table — each search restages its result, it does not accumulate across calls

paleobiology_get_taxon

Resolve a taxon by name or integer taxon_no to its full record and fossil temporal range — the name-resolution gateway the occurrence and diversity tools depend on.

• Returns accepted name, rank, higher classification, immediate parent, occurrence count, and FAD/LAD range in Ma

• The taxon_no it returns is the base_id accepted by paleobiology_search_occurrences, paleobiology_get_diversity, and paleobiology_search_collections

• show_children also lists immediate child taxa, up to 200 per call. children_truncated says whether more remain and children_offset says where the page started — advance children_offset by 200 while children_truncated is true to walk the whole child list. A taxon with over 200 immediate children returns a page, never a silently clipped list

• PBDB taxonomy is opinionated and can differ from GBIF's backbone, so the accepted name may differ from the searched name — the response surfaces both

paleobiology_get_diversity

Compute a diversity / origination / extinction curve for a clade across geologic time.

• Clade-inclusive base_name or base_id (exactly one is required; both together, or neither, is rejected at the tool boundary), bound by a named interval (e.g. Mesozoic) or a max_ma/min_ma range (min_ma must be strictly less than max_ma)

• count enum: genera, species, families; resolution enum: period, epoch, age

• The full bin set returns inline (a diversity series is a bounded set of geologic intervals)

• Counts reflect sampled diversity, biased by collection effort and rock availability — not true past diversity

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 location, age (named interval and Ma), formation and strata, lithology, depositional environment, and co-occurring-fossils count

• Filter by base_name or 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 (an unfiltered call is rejected before the upstream request)

• Same bounding-box and Ma-ordering rules as paleobiology_search_occurrences: lngmin/lngmax both or neither, min_ma strictly less than max_ma

• Results page inline via limit/offset; the response discloses when more remain

• Take a collection_no from a row — or the same bbox+interval — into paleobiology_search_occurrences to see the fauna found together

Related MCP server: usa-npn-mcp-server

Resources and prompts

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. occurrence_no and taxon_no are bare integers from those tools' output.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth (runs none by default — PBDB is keyless)

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

Paleobiology-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, and falls back to a PBDB lookup for the sub-stage and regional names that occurrence and collection rows report (Late Maastrichtian, Lancian), labeling each answer with its source and scale

• 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)

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

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

With bunx:

{
  "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):

{
  "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:

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd paleobiology-mcp-server

3. Install dependencies:

bun install

4. 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.

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

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)

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

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