MCP (Model Context Protocol) server for Biothings.io This server implements the Model Context Protocol (MCP) for BioThings, providing a standardized interface for accessing and manipulating biomedical data. MCP enables AI assistants and agents to access specialized biomedical knowledge through structured interfaces to authoritative data sources. Supported BioThings data sources include: - mygene.i
Add this skill
npx mdskills install longevity-genie/biothings-mcpWell-documented MCP server providing typed access to biomedical databases with comprehensive setup instructions
1[](https://mseep.ai/app/longevity-genie-biothings-mcp)23# biothings-mcp4[](https://github.com/longevity-genie/biothings-mcp/actions/workflows/tests.yml)5[](https://badge.fury.io/py/biothings-mcp)67MCP (Model Context Protocol) server for Biothings.io89This server implements the Model Context Protocol (MCP) for BioThings, providing a standardized interface for accessing and manipulating biomedical data. MCP enables AI assistants and agents to access specialized biomedical knowledge through structured interfaces to authoritative data sources. Supported BioThings data sources include:1011- [mygene.info](https://mygene.info) — Gene annotation and query service12- [myvariant.info](https://myvariant.info) — Variant annotation and query service13- [mychem.info](https://mychem.info) — Chemical compound annotation and query service1415If you want to understand more what is Model Context Protocol and how to use it more efficiently you can take [DeepLearning AI Course](https://www.deeplearning.ai/short-courses/mcp-build-rich-context-ai-apps-with-anthropic/) or just search for MCP videos on YouTube.161718## About MCP (Model Context Protocol)1920MCP is a protocol that bridges the gap between AI systems and specialized domain knowledge. It enables:2122- **Structured Access**: Direct connection to authoritative biomedical data sources23- **Natural Language Queries**: Simplified interaction with specialized databases24- **Type Safety**: Strong typing and validation through biothings-typed-client25- **AI Integration**: Seamless integration with AI assistants and agents2627## Available API Interfaces2829This server provides dedicated API interfaces for different BioThings data types, leveraging the `biothings-typed-client` library. These interfaces are implemented using the following tool handlers:3031- **Gene Interface**: `GeneTools` (wraps `GeneClientAsync`)32- **Variant Interface**: `VariantTools` (wraps `VariantClientAsync`)33- **Chemical Interface**: `ChemTools` (wraps `ChemClientAsync`)34- **Taxon Interface**: `TaxonTools` (wraps `TaxonClientAsync`)35- **Download Interface**: `DownloadTools` (provides file download and sequence analysis capabilities)3637## Local File Saving Features3839The server includes local file saving capabilities through the `DownloadTools` interface, which provides:4041### Download Tools42- **`download_entrez_data`**: Download data from NCBI Entrez databases (returns content as string)43- **`download_entrez_data_local`**: Download data from NCBI Entrez databases and save to local file4445### Output Directory Management46- **Default Location**: Files are saved to `biothings_output/` directory in the current working directory47- **Custom Location**: Use `--output-dir` parameter to specify a custom output directory48- **Automatic Creation**: Output directories are created automatically if they don't exist49- **Unique Filenames**: Auto-generated filenames include UUID prefixes to avoid conflicts5051### Supported File Formats52- **FASTA**: `.fasta` extension for sequence data53- **GenBank**: `.gb` extension for GenBank format data54- **Alignment**: `.aln` extension for alignment results55- **JSON**: `.json` extension for structured data56- **Text**: `.txt` extension for general text data5758## Quick Start5960### Installing uv6162```bash63# Download and install uv64curl -LsSf https://astral.sh/uv/install.sh | sh6566# Verify installation67uv --version68uvx --version69```7071uvx is a very nice tool that can run a python package installing it if needed.7273### Running with uvx7475You can run the biothings-mcp server directly using uvx without cloning the repository:7677#### STDIO Mode (for MCP clients that require stdio, can be useful when you want to save files)78```bash79# Run the server in STDIO mode (default mode)80uvx biothings-mcp8182# Or explicitly specify stdio mode83uvx --from biothings-mcp stdio8485# With custom output directory86uvx --from biothings-mcp stdio --output-dir ./my_data87```8889#### HTTP Streamable Mode (Web Server)90```bash91# Run the server in streamable HTTP mode on default port (3001)92uvx --from biothings-mcp server run9394# Run on a custom port95uvx --from biothings-mcp server run --port 80009697# Run on custom host and port98uvx --from biothings-mcp server run --host 0.0.0.0 --port 800099100# With custom output directory101uvx --from biothings-mcp server run --output-dir ./my_data102```103104#### SSE Mode (Server-Sent Events)105```bash106# Run the server in SSE mode on default port (3001)107uvx --from biothings-mcp sse108109# Run on a custom port110uvx --from biothings-mcp sse --port 8000111```112113The HTTP streamable mode will start a web server that you can access at `http://localhost:3001/mcp` (with documentation at `http://localhost:3001/docs`). The STDIO mode is designed for MCP clients that communicate via standard input/output, while SSE mode uses Server-Sent Events for real-time communication.114115116## Configuring your (Anthropic Claude Desktop, Cursor, Windsurf, etc.)117118We provide stdio configuration using the proxy (might need npx to run):119* mcp-config-remote.json - for remote configuration120* mcp-config-stdio.json - stdio configuration for localhost for MCP clients which do not support121122123### Inspecting Biothings MCP server124125If you want to inspect the methods provided by the MCP use npx (you may need to install nodejs and npm)126127Test your MCP setup with the MCP Inspector.128129If you want to inspect local streamable-http server you use:130131```bash132npx @modelcontextprotocol/inspector --config mcp-config.json --server biothings-mcp133```134135Add -remote suffix for the remote server.136137138If you want to inspect stdio local server you should use139140```bash141npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server biothings-mcp142```143144You can also run inspector manually and put server parameters in the interface:145```146npx @modelcontextprotocol/inspector147```148149After that you can explore its methods with MCP Inspector at http://127.0.0.1:6274150151152## Repository setup153154```bash155# Clone the repository156git clone https://github.com/longevity-genie/biothings-mcp.git157cd biothings-mcp158uv sync159```160161### Running the MCP Server162163If you already cloned the repo you can run the server with uv164165```bash166# Start the MCP server in HTTP streamable mode (default port 3001)167uv run server run168169# Run in STDIO mode170uv run stdio171172# Run in SSE mode173uv run sse174175# Run with custom port176uv run server run --port 8000177178# Run with custom output directory179uv run server run --output-dir ./my_data180```181182183### Integration with AI Systems184185To integrate this server with your MCP-compatible AI client, you can use one of the preconfigured JSON files provided in this repository:186187* **For connecting to a locally running server:** Use `mcp-config.json`. Ensure the server is running first, either via `uv run server` (see [Running the MCP Server](#running-the-mcp-server)) or `docker-compose up` (see [Docker Deployment](#docker-deployment)).188* **For connecting to the publicly hosted server:** Use `mcp-config-remote.json`. This connects to `https://biothings.longevity-genie.info/mcp` and doesn't require you to run anything locally.189190Simply point your AI client (like Cursor, Windserve, ClaudeDesktop, VS Code with Copilot, or [others](https://github.com/punkpeye/awesome-mcp-clients)) to use the appropriate configuration file.191192Here's an example of how the tools might appear in an MCP client like Cursor after configuration:193194195196## KNOWN ISSUES197198The library is beta-quality. The major problem right now is that LLM-s are often stupid and do not know how to put valid gene and gene variant symbols. We plan to mitigrate it by extending comments and providing additional method for entity resolution.199200## Testing & Verification201202Run tests for the API endpoint:203```bash204uv run pytest -vvv -s205```206207You can use MCP inspector with locally build MCP server same way as with uvx208209*Note: Using the MCP Inspector is optional. Most MCP clients (like Cursor, Windsurv, etc.) will automatically display the available tools from this server once configured. However, the Inspector can be useful for detailed testing and exploration.*210211*If you choose to use the Inspector via `npx`, ensure you have Node.js and npm installed. Using [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) is recommended for managing Node.js versions.*212213This opens a web interface where you can explore and test all available tools.214215216## Documentation217218For detailed documentation about the MCP protocol and its implementation, refer to:219- [MCP Protocol Documentation](https://modelcontextprotocol.org)220- [biothings-typed-client Documentation](https://github.com/longevity-genie/biothings-typed-client)221- [FastAPI-MCP Documentation](https://github.com/tadata-org/fastapi_mcp)222223## License224225This project is licensed under the MIT License.226227## Acknowledgments228229- [BioThings](https://biothings.io/) for the REST API and original [client library](https://github.com/biothings/biothings_client.py)230- [MCP Protocol](https://modelcontextprotocol.org) for the protocol specification231- [Pydantic](https://pydantic-docs.helpmanual.io/) for the data validation framework232- [FastAPI-MCP](https://github.com/tadata-org/fastapi_mcp) for the MCP server implementation233234- This project is part of the [Longevity Genie](https://github.com/longevity-genie) organization, which develops open-source AI assistants and libraries for health, genetics, and longevity research.235236We are supported by:237238[](https://heales.org/)239240*HEALES - Healthy Life Extension Society*241242and243244[](https://ibima.med.uni-rostock.de/)245246[IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research](https://ibima.med.uni-rostock.de/)247
Full transparency — inspect the skill content before installing.