Worms Marine Taxa Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.2.0Updated Oct 29, 2026

Resolve WoRMS marine species names; fetch classifications, synonyms, distributions, traits, and IDs.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Read-only WoRMS marine taxonomy server: resolve species names to AphiaIDs and fetch classifications, synonyms, distributions, traits and cross-referenced IDs.

What you can do
  • Resolve scientific names (exact or fuzzy) or one common name to AphiaIDs with accepted-name links
  • Fetch full taxon records, optionally with common names or source citations
  • Retrieve root-to-tip classification with optional direct children, and synonyms of the accepted taxon
  • Fetch recorded distributions with status, establishment, invasiveness and occurrence filters, optionally including synonyms
  • Fetch trait/attribute trees with inheritance and measurement-type filtering
  • Crosswalk AphiaIDs to nine external identifier systems or reverse an external ID
When to use it
Useful when an assistant needs authoritative marine species names, accepted-name corrections, classification lineages, synonym lists, distribution records or trait data, for example in marine biology research, biodiversity data cleaning or linking taxa to external databases.
Requirements
Either the public hosted endpoint (no install) or a local process via npx, which needs Node.js; a source build needs Bun 1.4.0+ or Node.js 24+. No API key or account: the WoRMS REST API is public. Optional framework settings include MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, MCP_AUTH_MODE and MCP_LOG_LEVEL. Network access to WoRMS is required.
Before you install
All eight tools are read-only, but calls are paced through one shared queue (one upstream request at a time, 500 ms apart) and the project asks for per-call retrieval with no bulk harvesting, so large batch jobs will be slow. Trait and distribution coverage is incomplete, so no rows does not prove absence. Reuse of results requires crediting the WoRMS Editorial Board and keeping per-record citations.

Installation

In SourceWeft

  1. Open Worms Marine Taxa Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fworms-marine-taxa-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "worms-marine-taxa": {
      "type": "http",
      "url": "https://worms-marine-taxa.caseyjhand.com/mcp"
    }
  }
}

README

@cyanheads/worms-marine-taxa-mcp-server

Resolve WoRMS marine species names; fetch classifications, synonyms, distributions, traits, and IDs via MCP. STDIO or Streamable HTTP.

8 Tools

Overview

Marine taxonomy from the World Register of Marine Species (WoRMS). Resolve scientific or common names to AphiaIDs, follow accepted names, and pull classifications, synonyms, distributions, traits, and external identifiers from the keyless WoRMS REST API.

Every AphiaID selector accepts a positive safe integer, a decimal string, or a canonical WoRMS LSID such as urn:lsid:marinespecies.org:taxname:137205; returned AphiaIDs remain numbers. For other LSIDs use worms_crosswalk_id with externalId and type: "lsid", or resolve a scientific name with worms_resolve_taxon.

Tools

ToolDescription
worms_resolve_taxonResolve scientific names (exact or fuzzy) or one common name to AphiaIDs, with accepted-name links
worms_get_taxonFetch full Aphia records by AphiaID, optionally with common names or sources
worms_get_classificationFetch the root-to-tip classification, optionally with direct children
worms_get_synonymsList synonyms of the accepted taxon behind an AphiaID
worms_get_distributionsFetch recorded distributions, filtered by status, establishment means, invasiveness, or occurrence
worms_get_traitsFetch attribute trees (body size, functional group, conservation listings) with sources and inheritance
worms_crosswalk_idMap an AphiaID to nine external identifier systems, or reverse an external ID
worms_list_referenceList identifier systems, statuses, environment flags, distribution filter values, ranks, and trait definitions

Capability reference

worms_resolve_taxon tool

  • A nonempty names list (no total-input ceiling, at most 50 per upstream request) or one vernacular, never both. fuzzy: true opts into TAXAMATCH matching; marineOnly and extantOnly default to true for names. Vernacular search matches a whole recorded common name, or with vernacularMatch: "contains" every recorded name containing the text (grouper finds no exact match but many by contains); it applies neither filter
  • Each result keeps its inputIndex (duplicates included), every match with status, validAphiaId, and validName, and a guidance line on a miss; continue with nextInputOffset and nextMatchOffset
  • Vernacular results page with the upstream offset (1-based, steps of 50) and the local resultOffset

worms_get_taxon tool

  • A nonempty aphiaIds list with no total-input ceiling, at most 50 fetched per request; continue with nextInputOffset using the unchanged list. Unknown IDs stay in position as found: false; every submitted element is validated before fetching
  • includeVernaculars: true (one ID only) adds common names, paged with vernacularOffset; a failed lookup returns vernacularError beside the record
  • includeSources: true (one ID only, not with includeVernaculars) adds the taxon's sources, such as its original description and basis of record, with reference, page, url, link, fulltext, and doi verbatim. Optional sourceUse: "original description" filters whole use values ignoring case before sourceOffset and the byte budget; blanks omit the filter, populated values stay untrimmed. Continue nextSourceOffset with unchanged options to repeat the full primary record and reconstruct every selected row in order
  • Successful source results report sourceTotalCount for the complete selected bibliography and unfilteredSourceCount only with an effective filter. Notices distinguish no matching use, an empty bibliography, and a past-end offset. A failed lookup returns sourcesError beside the record without counts; sourceUse is inactive without includeSources

worms_get_classification tool

  • One aphiaId; ranks is the root-to-tip lineage, with found: false when WoRMS has none
  • includeChildren: true adds one 50-row page of direct children (offset, marineOnly, extantOnly); a failed children lookup returns childrenError beside the lineage
  • The submitted AphiaID keeps its own recorded lineage. A notice names its linked accepted AphiaID, or the preferred AphiaID for an accepted alternative representation; a failed status lookup returns statusError beside the lineage

worms_get_synonyms tool

  • One aphiaId, accepted or not: synonyms are listed for its accepted taxon (validAphiaId), 50 per upstream offset
  • found and guidance separate a missing taxon from a name with no known accepted ID

worms_get_distributions tool

  • One aphiaId; optional recordStatus (valid, doubtful, inaccurate), establishmentMeans, invasiveness, and occurrence filters combine with AND. recordStatus ignores case and surrounding whitespace and echoes its lowercase code; the others match case-insensitive whole values without trimming populated strings, with observed values in worms_list_reference topic distribution_terms. Blank filters are omitted
  • Reports unfilteredCount and filteredCount; rows carry the locality, its MarineRegions locationId, and status fields in source order
  • WoRMS attaches records to individual name usages, so by default the tool reads that AphiaID's own records. includeSynonyms: true combines the accepted taxon's records with those of its synonyms, 10 synonyms per call, each row tagged sourceAphiaId; synonymUnion reports the window, the nextSynonymOffset to continue from, and any failedSynonyms
  • A notice names the linked accepted AphiaID, distinguishing an accepted alternative representation from its preferred AphiaID; without includeSynonyms, a failed status lookup returns statusError beside the rows

worms_get_traits tool

  • One aphiaId; includeInherited (default true) adds attributes recorded on higher taxa. On an accepted taxon WoRMS also returns attributes recorded on its synonyms whatever includeInherited is set to; inheritedFrom names the source taxon in both cases
  • A notice names the linked accepted AphiaID, distinguishing an accepted alternative representation from its preferred AphiaID; a failed status lookup returns statusError beside the attributes
  • Every node keeps nodeIndex, parentIndex, and depth from the full tree, so units and qualifiers stay attached to their values across pages; values and references are verbatim
  • measurementType (case-insensitive whole value, such as Body size) keeps each matching node with its subtree and ancestors, indices unchanged; totalCount counts that set and unfilteredCount the whole tree

worms_crosswalk_id tool

  • Exactly one of aphiaId (forward) or externalId with type (reverse). Forward reads one type or all nine: algaebase, bold, dyntaxa, fishbase, iucn, lsid, ncbi, tsn, gisd
  • Forward returns ids per type, typeTotals (0 means none recorded), and failedTypes for systems that errored; reverse returns found and the full record. IDs stay opaque strings, leading zeros included

worms_list_reference tool

  • topic: external_id_types, statuses, environment_flags, and distribution_terms are served offline; ranks and trait_types are read live
  • statuses covers the 28 statuses the WoRMS manual and REST API document, each with a one-line meaning and a group (accepted, unaccepted, uncertain, technical). A record's status can be the specific reason itself, such as junior subjective synonym, so test the group rather than status === "unaccepted"; the guide is non-exhaustive
  • distribution_terms lists the establishmentMeans, invasiveness, and occurrence values observed in WoRMS distributions, for the whole-value filters of worms_get_distributions; the lists are non-exhaustive
  • Pages with resultOffset; trait definitions keep their tree indices across pages

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.

WoRMS-specific:

  • Exact and TAXAMATCH fuzzy name matching with marine and extant filters; every match and record carries its accepted-name links
  • One shared request queue: one upstream request at a time, 500 ms between starts, a 45-second tool deadline, and an 8 MiB response ceiling
  • Per-call retrieval with no cache or bulk harvesting, as the WoRMS webservice guidance asks
  • Every response carries WoRMS attribution (doi:10.14284/170); credit the WoRMS Editorial Board and keep per-record citations when reusing results (terms)

Agent-friendly output:

  • Byte-bounded pages: reads return whole items within a 24,000-byte response and name the next offset (nextResultOffset, nextInputOffset, upstream page.nextOffset); a full 50-row upstream page reports hasMore: null rather than guessing
  • Unknown stays unknown: null and absent fields pass through, a null environment flag means not recorded, and empty evidence never claims biological absence
  • Partial failure: optional lookups (vernacularError, sourcesError, childrenError, statusError), synonym-union failedSynonyms, and crosswalk failedTypes keep the data that did arrive, with typed reasons and recovery hints

Getting started

Connect to the hosted instance, no install:

sh
claude mcp add --transport http worms-marine-taxa-mcp-server https://worms-marine-taxa.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add worms-marine-taxa-mcp-server -- npx -y @cyanheads/worms-marine-taxa-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "worms-marine-taxa-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/worms-marine-taxa-mcp-server"]    }  }}

No API key or account is needed: the WoRMS REST API is public. For Docker or a source build, see Running the server.

Configuration

The server has no variables of its own; these are the common framework settings.

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTHTTP server port.3010
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.stateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOGS_DIRDirectory for log files (Node.js only).<app-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable OpenTelemetry.false

See .env.example for the common framework overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

  • Clone and install:

    sh
    git clone https://github.com/cyanheads/worms-marine-taxa-mcp-server.gitcd worms-marine-taxa-mcp-server && bun installcp .env.example .env

  • Build and run the production version:

    sh
    # One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdio

  • Run checks and tests:

    sh
    bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suite

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/worms-marine-taxa-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/worms-marine-taxa-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/worms-marine-taxa-mcp-server:latest"]. To build locally, docker build -t worms-marine-taxa-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/mcp-server/tools/definitionsTool definitions (*.tool.ts). Eight read-only tools.
src/services/wormsWoRMS service: paced transport, normalization, domain schemas, response budgeting, and formatting.
docs/Design contract (design.md) and the generated directory tree.
tests/Service, tool-contract, and JSON-RPC integration tests.

Development guide

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

  • Handlers throw, framework catches; optional lookups report classified failures beside the primary data instead of discarding it
  • Register new tools in the createApp() arrays in src/index.ts
  • Internal imports are relative ESM paths with .js extensions
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Source: README.md at commit 5cd80f6

Tools

8

worms_list_reference

Worms List Reference

List supported external identifier systems, a non-exhaustive taxonomic-status guide grouped as accepted, unaccepted, uncertain, or technical, environment-flag semantics, observed worms_get_distributions filter values, live taxonomic ranks, or live trait definitions. Resume nextResultOffset as resultOffset with the same topic. Identifier codes, statuses, environment flags, and distribution terms are available offline. A record status can be the specific reason itself, such as junior subjective synonym, rather than unaccepted. IUCN identifiers are not threat categories; null flags mean not recorded. Trait definitions retain complete-tree preorder indices across pages; parents may be on earlier pages.

ParameterstopicrequiredresultOffset

worms_resolve_taxon

Worms Resolve Taxon

Resolve exact or explicitly fuzzy scientific names, or search one vernacular name as a whole recorded common name or, with vernacularMatch: "contains", as part of one. Names default to marine-or-brackish and extant taxa; vernacular cannot filter. Resume scientific segments with nextInputOffset and nextMatchOffset against unchanged names and options; inputIndex preserves duplicates and partialGroup identifies split groups. For vernacular, consume nextResultOffset within the same upstream offset before advancing page.nextOffset and resetting resultOffset to zero. Full 50-match upstream groups remain completeness-unknown; accepted-name fields do not choose an ambiguous match.

ParametersfuzzynamesoffsetextantOnlymarineOnlyvernacularinputOffsetmatchOffsetresultOffsetvernacularMatch

worms_get_taxon

Worms Get Taxon

Retrieve full Aphia records by numeric IDs or canonical WoRMS LSIDs in byte-budgeted segments. Resume nextInputOffset as inputOffset using unchanged aphiaIds and options; inputIndex preserves duplicate and missing positions. includeVernaculars (common names) or includeSources (original description, basis of record, and other sources) requires one submitted ID, one of the two per call; resume nextVernacularOffset as vernacularOffset or nextSourceOffset as sourceOffset, repeating the full primary record. sourceUse filters whole use values ignoring case before sourceOffset; populated values are not trimmed. Successful source results report sourceTotalCount before slicing and unfilteredSourceCount only with an effective filter. Optional failure retains the record without source counts; unknown facts remain omitted or null.

ParametersaphiaIdsrequiredsourceUseinputOffsetsourceOffsetincludeSourcesvernacularOffsetincludeVernaculars

worms_get_classification

Worms Get Classification

Retrieve root-to-tip classification and optional direct children for an AphiaID or canonical WoRMS LSID. resultOffset indexes lineage followed by fetched children; consume nextResultOffset with unchanged options and upstream offset before advancing page.nextOffset and resetting resultOffset to zero. Missing ranks remain unknown; child offset and filters are inactive without includeChildren. A full fetched 50-row child page has uncertain continuation and can lead to an empty page. The submitted ID keeps its own recorded lineage; a notice names its linked accepted ID, distinguishing an accepted alternative representation from its preferred ID.

ParametersoffsetaphiaIdrequiredextantOnlymarineOnlyresultOffsetincludeChildren

worms_get_synonyms

Worms Get Synonyms

Retrieve synonyms for the accepted taxon linked from an AphiaID obtained with worms_resolve_taxon. Consume nextResultOffset within the same upstream offset before advancing page.nextOffset and resetting resultOffset to zero. A present name without an accepted ID has no synonym lookup; inspect it with worms_get_taxon. A full fetched 50-row page has uncertain continuation and may lead to an empty page.

ParametersoffsetaphiaIdrequiredresultOffset

worms_get_distributions

Worms Get Distributions

Retrieve recorded distributions for an AphiaID or canonical WoRMS LSID in byte-budgeted segments; resume nextResultOffset as resultOffset with unchanged selectors and filters. WoRMS attaches records to individual name usages, so one AphiaID's rows can miss those of its synonyms: includeSynonyms combines the accepted taxon's rows with those of up to 10 synonyms per call, each row tagged sourceAphiaId; consume nextResultOffset before advancing synonymOffset to synonymUnion.nextSynonymOffset with resultOffset 0. Filters apply to the complete fetched set before pagination and combine by conjunction: recordStatus normalizes case and surrounding whitespace before exact matching; others use case-insensitive whole-value equality without trimming. Rows retain duplicates and source order; no rows does not prove biological or taxon absence. A notice names the linked accepted ID, distinguishing an accepted alternative representation from its preferred ID.

ParametersaphiaIdrequiredoccurrenceinvasivenessrecordStatusresultOffsetsynonymOffsetincludeSynonymsestablishmentMeans

worms_get_traits

Worms Get Traits

Retrieve recorded attributes for an AphiaID or canonical WoRMS LSID, including inherited attributes by default. Resume nextResultOffset as resultOffset with unchanged selectors and options. Whole rows retain original preorder nodeIndex and parentIndex across pages; parents may be on earlier pages. measurementType keeps each matching node with its subtree and ancestors, indices unchanged; totalCount counts that set and unfilteredCount the whole tree. Values, references and inheritance markers remain unchanged; on an accepted taxon WoRMS also returns attributes recorded on its synonyms whatever includeInherited is set to, marked by inheritedFrom. A notice names the linked accepted ID, distinguishing an accepted alternative representation from its preferred ID. Missing traits do not prove biological absence; IUCN list membership is not a threat category.

ParametersaphiaIdrequiredresultOffsetmeasurementTypeincludeInherited

worms_crosswalk_id

Worms Crosswalk Id

Crosswalk an AphiaID from worms_resolve_taxon to one or all nine external identifier systems, or reverse an externalId with required type to a full taxon record. Supply exactly one selector. Forward resultOffset indexes whole identifiers across types in requested order; resume nextResultOffset with unchanged selectors. typeTotals distinguishes successful absence from IDs on another segment; failed types remain separate. IDs stay opaque, including leading zeros and LSIDs. No IDs cannot establish taxon absence; IUCN identifiers are not threat categories.

ParameterstypeaphiaIdexternalIdresultOffset

Version history

4
  1. v0.2.0LatestOct 29, 2026
  2. v0.1.3Oct 25, 2026
  3. v0.1.2Oct 21, 2026
  4. v0.1.1Oct 21, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts