@cyanheads/paleobiology-mcp-server

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

Resources

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.

Related MCP server: mcp-macrostrat

Capability reference

paleobiology_search_occurrences tool

• Requires at least one taxon, time, geographic, environment, or collection_no filter. Use base_name or base_id for a clade, taxon_name for an exact match; page with limit (default 100, max 500) and offset

• Returns modern and paleo coordinates, named intervals and Ma ages, strata, and higher classification. totalCount and the notice report PBDB's true match count and next offset; rejected filters carry missing_filter, conflicting_taxon_filter, incomplete_bbox, or inverted_ma_range

• Large pages spill to DataCanvas and return canvas_id + table_name for SQL. Reusing a canvas_id replaces that canvas's occurrence table; a page that fits inline stages nothing

paleobiology_get_taxon tool

• Resolve by name or taxon_no to accepted name, rank, classification, parent, occurrence count, and FAD/LAD range in Ma. The returned taxon_no is the base_id accepted by occurrence, diversity, and collection searches

• show_children adds up to 200 immediate child taxa per call; children_truncated and children_offset say whether and where to continue

• Typed errors: taxon_not_found, missing_selector

paleobiology_get_diversity tool

• Requires a clade (base_name or base_id), optionally bounded by interval or max_ma/min_ma. Choose count (genera, species, families) and resolution (period, epoch, age); defaults are genera by period

• Returns the full bin set inline, oldest-first, with sampled, implied, origination, extinction, range-through, and occurrence counts

• Typed errors: missing_filter, conflicting_taxon_filter, inverted_ma_range

paleobiology_list_intervals tool

• Filter by name, a min_ma/max_ma overlap window, or level (eon, era, period, epoch, age); omit filters to browse the bundled ICS scale

• Returns interval rank, Ma boundaries, parent_no, and an upstream scale where available. source (bundled_ics / pbdb_upstream) and snapshot_version identify the source; names outside the snapshot use PBDB

• Typed errors: interval_not_found for an unmatched name; retryable interval_lookup_unavailable when PBDB cannot resolve a name outside the snapshot

paleobiology_search_collections tool

• Requires at least one taxon, time, geographic, formation, lithology, or environment filter. Page with limit (default 100, max 500) and offset

• Returns locality coordinates, age, strata, lithology, environment, and n_occs, with totals and truncation guidance. Pass collection_no to paleobiology_search_occurrences for the fauna 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 — callable only when PALEOBIOLOGY_DATAFRAME_DROP_ENABLED=true, absent from tools/list otherwise; the manifest retains its enable hint

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

• PBDB's accepted taxonomy may differ from the searched name or other backbones. Diversity counts reflect sampling and collection effort, rather than true past diversity

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:

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

{
  "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.4 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)

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.