Purpose
biothings-mcp is an MCP (Model Context Protocol) server for BioThings, providing a standardized interface for accessing and manipulating biomedical data. MCP enables AI assistants and agents to access specialized biomedical knowledge from authoritative data sources through structured interfaces. This project belongs to the Longevity Genie organization, which develops open-source AI assistants and libraries for health, genetics, and longevity research.
Supported BioThings Data Sources
- mygene.info — gene annotation and query service
- myvariant.info — variant annotation and query service
- mychem.info — compound annotation and query service
Main Capabilities
The server is based on the biothings-typed-client library and provides specialized API interfaces for different BioThings data types, implemented through the following tool handlers:
- Gene interface: GeneTools (wraps GeneClientAsync)
- Variant interface: VariantTools (wraps VariantClientAsync)
- Chemical interface: ChemTools (wraps ChemClientAsync)
- Taxon interface: TaxonTools (wraps TaxonClientAsync)
- Download interface: DownloadTools (provides file download and sequence analysis capabilities)
The DownloadTools interface provides local file saving capabilities, including:
- download_entrez_data: downloads data from the NCBI Entrez database (returns content as a string)
- download_entrez_data_local: downloads data from the NCBI Entrez database and saves it to a local file
Usage
Running with uvx
uvx is a tool that can install and run Python packages on demand. You can run the biothings-mcp server directly with uvx without cloning the repository. HTTP streamable mode starts a web server, accessible via http://localhost:3001/mcp (documentation at http://localhost:3001/docs）。STDIO mode is for MCP clients that communicate via standard input/output, and SSE mode uses Server-Sent Events for real-time communication.
Configuring the MCP Client
The project provides stdio configurations using a proxy (may require npx to run):
- mcp-config-remote.json — remote configuration
- mcp-config-stdio.json — localhost stdio configuration for MCP clients that do not support remote
Repository Setup and Running
If you have cloned the repository, you can run the server with uv.
Integration with AI Systems
To integrate this server with MCP-compatible AI clients, you can use the preconfigured JSON files provided in the repository:
- Connect to a locally running server: use mcp-config.json, and first start the server via uv run server or docker-compose up.
- Connect to a publicly hosted server: use mcp-config-remote.json, connecting to https://biothings.longevity-genie.info/mcp，无需在本地运行任何内容。 Point the AI client (such as Cursor, Windsurf, Claude Desktop, VS Code with Copilot, etc.) to the corresponding configuration file.
Inspecting the Server
You can use npx to inspect the methods provided by MCP, which may require installing Node.js and npm. You can use MCP Inspector to test the MCP setup. When inspecting a local streamable-http server, use the corresponding address; for a remote server, add the -remote suffix. When inspecting a local stdio server, use the corresponding command. You can also run the inspector manually and enter the server parameters in the interface, after which you can http://127.0.0.1:6274 Explore its methods through MCP Inspector.
Testing and Validation
Run API endpoint tests. You can use MCP inspector through a locally built MCP server, just like using uvx. Note: Using MCP Inspector is optional. Most MCP clients (such as Cursor, Windsurf, etc.) will automatically display the tools provided by this server after configuration, but Inspector is useful for detailed testing and exploration. If you choose to use Inspector via npx, make sure Node.js and npm are installed, and using nvm to manage Node.js versions is recommended.
Output Directory Management
- Default location: Files are saved to the biothings_output/ directory under the current working directory
- Custom location: Use the --output-dir parameter to specify a custom output directory
- Automatic creation: If the output directory does not exist, it will be created automatically
- Unique filenames: Automatically generated filenames include a UUID prefix to avoid conflicts
Supported File Formats
- FASTA: .fasta extension, for sequence data
- GenBank: .gb extension, for GenBank format data
- Alignment: .aln extension, for alignment results
- JSON: .json extension, for structured data
- Text: .txt extension, for general text data
Use Cases
Suitable for scenarios where an AI assistant or agent needs to access authoritative biomedical data sources, including gene annotation queries, genetic variant queries, compound annotation queries, taxonomy information queries, and downloading sequence data from NCBI Entrez and saving it locally for analysis.
Limitations
This library is beta quality. The current main issue is that LLMs are often not smart enough to know how to fill in valid gene and genetic variant symbols. The project plans to mitigate this issue by expanding annotations and providing additional entity resolution methods.
Project Information
This project uses the MIT license.
Acknowledgments: BioThings provides the REST API and the original client library; MCP Protocol provides the protocol specification; Pydantic provides the data validation framework; FastAPI-MCP provides the MCP server implementation.
Supporters: HEALES - Healthy Life Extension Society; IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research.
About MCP
MCP is a protocol that connects AI systems with specialized domain knowledge, supporting structured access, natural language queries, type safety (strong typing and validation through biothings-typed-client), and AI integration. To learn more about MCP and how to use it more efficiently, you can refer to the DeepLearning AI course or search for MCP videos on YouTube.
For detailed documentation, refer to: MCP Protocol Documentation, biothings-typed-client Documentation, FastAPI-MCP Documentation.
