paleobiology-mcp-server

<div align="center">
  <h1>@cyanheads/paleobiology-mcp-server</h1>
  <p><b>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.</b>
  <div>8 Tools • 2 Resources</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/paleobiology-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/paleobiology-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/paleobiology-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/paleobiology-mcp-server/releases/latest/download/paleobiology-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=paleobiology-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcGFsZW9iaW9sb2d5LW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22paleobiology-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fpaleobiology-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://paleobiology.caseyjhand.com/mcp](https://paleobiology.caseyjhand.com/mcp)

</div>

---

## 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` <sub>tool</sub>

- `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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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` <sub>tool</sub>

- 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 `