bio-agents

Bio-Agents MCP provides modular services for interacting with biological data sources. It exposes two primary MCP servers built on FastMCP: one for the Protein Data Bank (PDB) API and another for the ChEMBL chemical database API. These servers can be run independently or together via Docker Compose. The system is designed to be used through an LLM-driven client (LLM Client) that can query biological data, retrieve structural information, annotations, and chemical data, and present results through a web UI or terminal interface. Each server is intended to be run as its own microservice, allowing you to scale only the components you need.

To use the services, start the backend containers (or the full docker-compose stack) and then interact with the web UI at http://localhost:8000 or connect via the LLM Client to issue natural language queries. The PDB MCP Server handles PDB-specific endpoints like structures, annotations, and related data; the ChEMBL MCP Server provides access to chemical databases and related properties. The LLM Client module orchestrates calls to these services and presents results to the user, supporting asynchronous operations and rich tooling through the FastMCP framework.

Prerequisites:

• Docker and Docker Compose installed on your machine
• Git to clone the repository
• Basic familiarity with Docker workflows

Step 1: Clone the repository

• git clone <repository-url>
• cd bio-agents

Step 2: Configure environment

• cp .env.example .env
• Edit .env to set any required environment variables (e.g., API keys, database endpoints, or service flags). The README indicates using an .env file for containers.

Step 3: Build Docker images (per-module)

• docker build -t protein_data_bank_mcp protein_data_bank_mcp
• docker build -t chembl_mcp chembl_mcp

Step 4: Run all services with Docker Compose (recommended)

• docker-compose up -d

Step 5: Alternatively, run individual modules

• docker run -i --env-file .env protein_data_bank_mcp
• docker run -i --env-file .env chembl_mcp

Step 6: Launch the web UI

• make run-chainlit or visit http://localhost:8000 depending on how you wired the chain interface in your setup.

Notes:

• The project uses a FastMCP framework; ensure compatible Python/Node versions as indicated in submodule READMEs if you encounter version errors.
• If you customize ports or endpoints, adjust docker-compose.yml and environment variables accordingly.

Tips and common issues:

• Ensure .env is properly configured before starting containers; missing keys can cause startup failures.
• When running individual modules, remember to expose any required ports or supply API keys via environment variables.
• If you update a module, rebuild its image (docker build -t <module-name> .) and restart the container.
• The Makefile provides convenience targets (build, up, down, restart, run-chainlit); use make help to see available options.
• Docker Compose is the recommended approach to run all services together; use docker-compose up -d for a quick start and docker-compose down to stop them.
• Logs are essential for debugging; use docker-compose logs -f or docker logs <container> to inspect startup errors.