Skip to main content
Glama

Biologist Model Context Protocol (MCP) Server

TypeScript MCP License: MIT

A Model Context Protocol (MCP) server providing deep LLM-agent tool, resource, and prompt integrations with Biologist — an open-source computational research platform and quantitative analytical laboratory for comparative biology, ecology, and organismal taxonomy.


Overview

The biologist-mcp server enables AI agents (Claude Code, Cursor, Gemini CLI, Antigravity) to query, manipulate, cluster, and synthesize ecological and taxonomic domain models directly over standard input/output (stdio):

  • 51 Registered MCP Tools across 8 functional modules (Search, Biomes, Species, Organisms, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).

  • 4 Registered MCP Resources exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.

  • 3 MCP Prompt Templates for comparative biological studies, cluster synthesis monographs, and evolutionary convergence inquiries.

  • 1024-dimensional semantic manifold querying via PostgreSQL pgvector HNSW indexes.


Related MCP server: AgentBase

Architectural Mapping

Tier / Domain

Model

Table Name

MCP Module / Tools

Tier 1

Biomes & Climatic Zones

biomes

list_biomes, get_biome, create_biome, update_biome, delete_biome, upsert_biomes_batch, populate_biomes, populate_biome_species

Tier 2

Species & Keystone Taxa

species

list_species, get_species, create_species, update_species, delete_species, upsert_species_batch, generate_species_embedding, populate_species_organisms, populate_species_bulk

Tier 3

Individual Organisms & Morphs

organisms

list_organisms, get_organism, create_organism, update_organism, delete_organism, upsert_organisms_batch, generate_organism_embedding, populate_organisms_bulk

Clustering

15-Level Agglomerative

cluster_snapshots, cluster_groups

compute_clusters, create_cluster_snapshot, list_cluster_snapshots, get_cluster_snapshot, delete_cluster_snapshot, list_cluster_groups, get_cluster_group

Synthesis

Multi-Stage Map-Reduce

cluster_reports, cluster_report_summaries

list_cluster_reports, get_cluster_report, create_cluster_report, delete_cluster_report, generate_deep_synthesis, list_report_summaries, get_report_summary, list_report_sub_reports, get_report_sub_report

Global Search

Cross-Catalog pgvector

Multi-table

search, find_counterparts

Platform

Jobs & System Info

Multi-service

list_jobs, get_job_status, wait_for_job, get_platform_status, get_settings, update_context_window, trigger_bulk_embeddings, get_openapi_spec


Installation & Setup

Prerequisites

  • Node.js 20+

  • Running instance of Biologist (http://localhost:3000)

Build

git clone https://github.com/leouofa/biologist-mcp.git
cd biologist-mcp
npm install
npm run build

Configuration

Environment Variables

Configure via .env file or export in your shell:

# Base URL for the Biologist Rails API (v1)
BIOLOGIST_API_BASE_URL=http://localhost:3000/api/v1

# Optional Bearer Token for protected endpoints
BIOLOGIST_API_TOKEN=

# Request timeout in milliseconds (default: 60000)
BIOLOGIST_TIMEOUT_MS=60000

# Enable debug logging
BIOLOGIST_DEBUG=false

CLI Options

biologist-mcp [options]

Options:
  -u, --url <url>        Biologist API base URL (default: http://localhost:3000/api/v1)
  -k, --api-key <key>    Optional API key / Bearer token
  -t, --timeout <ms>     Request timeout in milliseconds (default: 60000)
  -d, --debug            Enable debug logging
  -h, --help             Display this help message

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "biologist": {
      "command": "node",
      "args": ["/path/to/biologist-mcp/dist/index.js"],
      "env": {
        "BIOLOGIST_API_BASE_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

Antigravity

Add to your antigravity_config.json or MCP settings:

{
  "mcpServers": {
    "biologist": {
      "command": "node",
      "args": ["/path/to/biologist-mcp/dist/index.js"],
      "env": {
        "BIOLOGIST_API_BASE_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

MCP Resources

URI Template

MIME Type

Description

biologist://status

application/json

Real-time platform health, counts, and LLM configuration

biologist://biomes

application/json

Catalog of all registered biomes

biologist://snapshots/{id}

application/json

Frozen cluster snapshot data with members and reports

biologist://reports/{id}

text/markdown

Generated synthesis monograph in academic Markdown


MCP Prompts

  1. comparative_biological_analysis: Rigorous comparative analysis between two species or organisms using semantic manifold distance, trophic strategies, and functional adaptations.

  2. biological_cluster_monograph: Academic synthesis monograph prompt for drafting a formal treatise from frozen archetype clusters.

  3. evolutionary_convergence_inquiry: Cross-biome convergence analysis prompt investigating analog adaptations across independent lineages.


Testing

# Run test suite
npm test

# Run tests in watch mode
npm run test:watch

License

This project is open-source software licensed under the MIT License.

Available Tools

51 tools
compute_clustersB

Compute live connected-components vector clusters for Species or Organisms across biomes without modifying the database.

Inputs: force, level, target_type, full_coverage.

create_biomeC

Create a new biome record in the catalog.

Inputs: name (required), description.

create_cluster_reportC

Initiate a 2-Phase Map-Reduce synthesis report on a frozen cluster snapshot.

Inputs: prompt (required), cluster_snapshot_id (required).

create_cluster_snapshotA

Compute connected-components clustering and freeze it immediately into an immutable database snapshot.

Inputs: level (required), title (required), target_type (required), full_coverage.

create_organismC

Create a new individual organism/morph record under a parent species.

Inputs: name (required), species_id (required), themes, description.

create_speciesC

Create a new species record under a parent biome.

Inputs: name (required), biome_id (required), themes, description.

delete_biomeA

Delete a biome and its cascaded species and organisms.

Inputs: id (required).

delete_cluster_reportA

Delete a synthesis report along with its intermediate summaries and sub-reports.

Inputs: id (required).

delete_cluster_snapshotB

Delete a frozen cluster snapshot along with its cascaded cluster groups and synthesis reports.

Inputs: id (required).

delete_organismC

Delete an individual organism record.

Inputs: id (required).

delete_speciesB

Delete a species and its associated individual organisms.

Inputs: id (required).

find_counterpartsA

Find nearest ecological counterparts or convergent evolutionary analogs to a specified species or organism using 1024-dimensional pgvector cosine distance.

Inputs: id (required), entity_type (required), limit, threshold.

generate_deep_synthesisB

Initiate a 3-Phase Hierarchical Deep Synthesis monograph, reusing Phase 1 summaries from a completed parent report.

Inputs: report_id (required), batch_size.

generate_organism_embeddingB

Generate or refresh the 1024-dimensional semantic embedding for an individual organism.

Inputs: id (required), sync.

generate_species_embeddingB

Generate or refresh the 1024-dimensional semantic embedding for a species.

Inputs: id (required), sync.

get_biomeA

Retrieve details of a single biome including its member species.

Inputs: id (required), include_species.

get_cluster_groupA

Retrieve details of a specific archetype cluster group with all member species or organisms.

Inputs: id (required), include_members.

get_cluster_reportB

Retrieve complete scholarly biological report content, progress percentage, markdown monograph, and intermediate summaries.

Inputs: id (required), include_summaries, include_sub_reports.

get_cluster_snapshotC

Retrieve details of a frozen cluster snapshot including member groups and generated synthesis reports.

Inputs: id (required), include_groups, include_members, include_reports.

get_job_statusB

Check the status, progress, and result of an ActiveJob/Sidekiq background task.

Inputs: job_id (required).

get_openapi_specA

Retrieve the raw OpenAPI 3.1 specification for the Biologist API.

Inputs: no named parameters.

get_organismA

Retrieve details of a single individual organism including parent species and biome.

Inputs: id (required), include_embedding.

get_platform_statusA

Get overall platform health, catalog entity counts, embedding coverage stats, and active LLM configuration.

Inputs: no named parameters.

get_report_sub_reportC

Retrieve a single Phase 2 batch analysis.

Inputs: id (required).

get_report_summaryC

Retrieve a single Phase 1 per-cluster scholarly summary.

Inputs: id (required).

get_settingsA

Get embedding completion metrics for Species and Organisms, active embedding/LLM parameters, and context window presets.

Inputs: no named parameters.

get_speciesB

Retrieve details of a single biological species including its biome and child organisms.

Inputs: id (required), include_embedding, include_organisms.

list_biomesB

List biomes (global ecosystems, climatic zones, and primary environmental regimes) registered in Biologist with species counts.

Inputs: q, limit, offset, include_species.

list_cluster_groupsC

List all archetype cluster groups belonging to a specific frozen snapshot.

Inputs: cluster_snapshot_id (required), limit, offset, include_members.

list_cluster_reportsC

List generated multi-phase comparative biology and ecological manifold synthesis reports.

Inputs: limit, offset, status, is_detailed, +2 more.

list_cluster_snapshotsC

List frozen archetype cluster snapshots in Biologist.

Inputs: limit, offset, target_type.

list_jobsB

List recent asynchronous background jobs (embedding calculations, LLM discoveries, synthesis reports).

Inputs: limit.

list_organismsB

List individual organisms (morphs, castes, sexual dimorphisms, life-history stages) with filtering by species, biome, themes, and embedding status.

Inputs: q, limit, theme, offset, +4 more.

list_report_sub_reportsB

List all Phase 2 intermediate batch analyses belonging to a detailed synthesis report.

Inputs: cluster_report_id (required).

list_report_summariesB

List all Phase 1 per-cluster analyses belonging to a synthesis report.

Inputs: cluster_report_id (required).

list_speciesB

List species registered in Biologist with filtering by biome, themes, embedding status, and search keywords.

Inputs: q, limit, theme, offset, +4 more.

populate_biomesB

Trigger LLM discovery to populate major global biomes and environmental regimes.

Inputs: no named parameters.

populate_biome_speciesC

Discover and populate canonical species for a specific biome via LLM generation.

Inputs: id (required), sync, count.

populate_organisms_bulkB

Trigger LLM discovery to populate individual organisms across all registered species.

Inputs: no named parameters.

populate_species_bulkB

Trigger LLM discovery to populate species across all registered biomes.

Inputs: no named parameters.

populate_species_organismsC

Discover and populate individual organisms, castes, or morphs for a specific species via LLM generation.

Inputs: id (required), sync, count.

trigger_bulk_embeddingsC

Enqueue bulk embedding generation for all Species or Organisms.

Inputs: model_type (required), only_missing.

update_biomeC

Update an existing biome's name or description.

Inputs: id (required), name, description.

update_context_windowC

Dynamically update the active LLM context window token size.

Inputs: context_window (required).

update_organismC

Update an existing organism's attributes, species assignment, or themes.

Inputs: id (required), name, themes, species_id, +1 more.

update_speciesC

Update an existing species's attributes, biome assignment, or themes.

Inputs: id (required), name, themes, biome_id, +1 more.

upsert_biomes_batchB

Batch insert or update biomes matching case-insensitively on name.

Inputs: biomes (required).

upsert_organisms_batchB

Batch insert or update organisms scoped to a specific species matching case-insensitively on name.

Inputs: organisms (required), species_id (required).

upsert_species_batchB

Batch insert or update species scoped to a specific biome matching case-insensitively on name.

Inputs: species (required), biome_id (required).

wait_for_jobA

Poll a background job until completion or failure with configurable timeout.

Inputs: job_id (required), timeout_ms, poll_interval_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 51 tools

    Disambiguation3/5

    The tool set is organized by resource, but several tools have overlapping boundaries: get_platform_status and get_settings both expose embedding/LLM configuration, while create_*, upsert_*_batch, and populate_* provide three different creation paths for biomes, species, and organisms. report_summary/sub_report/cluster_report tools are distinguishable, but the sheer number of similarly named lifecycle tools increases misselection risk.

    Naming Consistency4/5

    Most names follow a clear snake_case verb_noun pattern (list_biomes, create_species, delete_organism, generate_organism_embedding). There are minor deviations such as the bare 'search' and some noun-heavy report names, but the convention is generally predictable.

    Tool Count2/5

    At 51 tools, the surface is heavy for any MCP server and includes many near-parallel CRUD, batch, populate, embedding, snapshot, reporting, job, and system tools. The domain is broad, but the count still feels excessive relative to the core workflow.

    Completeness4/5

    The server covers full CRUD lifecycles for biomes, species, organisms, cluster snapshots, and reports, plus embedding, job, search, and system operations. Minor gaps exist (for example, no direct update/delete for cluster groups, and snapshot immutability is intentional), but the main workflows are well supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      Enables AI agents to query an air-gapped enterprise knowledge vault via seven MCP tools for deterministic and hybrid retrieval, entity graph traversal, context compression, archive inspection, onboarding scans, and node status.
      7
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to run hybrid retrieval, build token-budgeted attributed context packs, answer questions with citation and groundedness-gated release, explore temporal graph entities, evaluate claim support, and ingest screened, embedded documents through typed MCP tools.
      Apache 2.0