Biosamples - MCP

A Model Context Protocol (MCP) server for biological sample checklist validation and recommendation.

Built as part of GSoC 2026 proposal preparation for EMBL-EBI (Project: Expose BioSamples Submission and Search Capabilities as MCP Tools for AI-Assisted Metadata Interaction).

What it does

Exposes 3 MCP tools that an LLM (e.g. Claude) can call:

Related MCP server: bvbrc-mcp-server

Architecture

Key findings from API research

• BioValidator (/biosamples/validate) validates JSON structure but does not enforce checklist mandatory fields — the MCP server's scoring engine fills this gap independently

• ENA Browser XML API (/ena/browser/api/xml/{id}) is the reliable public source for checklist field definitions

• BioSamples JSON Schema Store (internal MongoDB) is not publicly accessible — flagged as a risk in the GSoC proposal with ENA XML as a confirmed working alternative

• Validation errors return as structured {dataPath, errors} arrays — machine-parseable and LLM-friendly

Setup

git clone https://github.com/rithvik318/biosamples-mcp
cd biosamples-mcp
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux
pip install -r requirements.txt

Run

python server.py

Test with MCP Inspector

npx @modelcontextprotocol/inspector python D:\biosamples-mcp\server.py

Open http://localhost:6274 and connect using:

• Command: D:\biosamples-mcp\venv\Scripts\python.exe

• Arguments: D:\biosamples-mcp\server.py

Example tool calls

validate_sample

{
  "sample_name": "soil sample from Delhi",
  "characteristics": "{\"organism\": [{\"text\": \"soil metagenome\"}], \"collection_date\": [{\"text\": \"2024-01-01\"}], \"geographic_location_country_andor_sea\": [{\"text\": \"India\"}]}",
  "checklist_id": "ERC000011"
}

recommend_checklist

{
  "sample_name": "soil metagenome sample",
  "characteristics": "{\"organism\": [{\"text\": \"soil metagenome\"}], \"collection_date\": [{\"text\": \"2024-01-01\"}]}",
  "top_n": 3
}

Technologies

• Python 3.10+

• MCP Python SDK

• httpx (async HTTP)

• xml.etree.ElementTree (XML parsing)

• Tested with MCP Inspector v0.21.1