biothings

The biothings-mcp server implements the Model Context Protocol (MCP) for BioThings data sources, exposing structured interfaces to gene, variant, chemical, and taxon data from mygene.info, myvariant.info, and mychem.info. It also offers a DownloadTools interface for file downloads and sequence analyses. You can run the server in multiple modes depending on your integration needs: STDIO for MCP clients that communicate via standard input/output, HTTP streamable mode to serve a web API at a local port, or SSE mode for real-time updates. Once running, you can connect your MCP-enabled AI client (like Cursor, Windserve, Claude Desktop, or Copilot-enabled IDEs) to the appropriate endpoints and call methods such as GeneTools, VariantTools, ChemTools, TaxonTools, and DownloadTools. The server also includes a local file-saving feature with a default output directory biothings_output/ and supports configuring a custom --output-dir when needed.

Interface overview:

• Gene Interface: GeneTools (wraps GeneClientAsync)
• Variant Interface: VariantTools (wraps VariantClientAsync)
• Chemical Interface: ChemTools (wraps ChemClientAsync)
• Taxon Interface: TaxonTools (wraps TaxonClientAsync)
• Download Interface: DownloadTools (downloads data from NCBI Entrez and performs sequence analyses)

To inspect available methods, you can use the MCP Inspector tool against your running server configuration, typically via an mcp-config.json or mcp-config-stdio.json setup. For local testing, you can start the server in STDIO mode for MCP clients that need stdio and then connect the inspector to verify endpoints and data shapes before integrating into your AI workflows.

Prerequisites:

• Python 3.8+ (recommended latest stable)
• Optional: Node.js and npm if you plan to test via npm-based tooling, though the Biothings MCP server itself runs in Python/uvx in this setup

Installation steps (two common paths):

Option A: Install and run the server via pip (from PyPI)

1. Upgrade pip: python -m pip install --upgrade pip
2. Install the biothings-mcp package from PyPI: pip install biothings-mcp
3. Run the server using uvx (provided by uv) to host the package locally: uvx biothings-mcp

Option B: Install from source (cloning the repo)

1. Clone the repository: git clone https://github.com/longevity-genie/biothings-mcp.git cd biothings-mcp
2. Create and activate a virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # on macOS/Linux venv\Scripts\activate # on Windows
3. Install dependencies (if any are listed in setup.py/requirements.txt): pip install -r requirements.txt # if present
4. Install the package in editable mode (optional for development): pip install -e .
5. Run the server with uvx: uvx biothings-mcp

Notes:

• The Quick Start guide demonstrates using uvx to run without cloning, which is convenient for quick testing.
• If you plan to deploy in Docker, see the Docker deployment notes in the repository readme (if present).

Tips and known considerations:

• Output directory: By default, biothings_output/ is used. You can override with --output-dir when running via uvx biothings-mcp or via your client configuration.
• Networking: HTTP streamable mode runs by default on port 3001; you can override with port in the server run command (e.g., uv run server run --port 8000) when using uv for local testing. SSE mode is available for real-time event streams.
• Inspection: Use MCP Inspector to verify methods and interfaces exposed by GeneTools, VariantTools, ChemTools, TaxonTools, and DownloadTools against mcp-config.json or mcp-config-stdio.json.
• Data sources: The server provides access to BioThings data through the corresponding typed clients. Ensure network access to mygene.info, myvariant.info, and mychem.info if you plan to query live data.
• Environment variables: If you customize the runtime, you may want to expose BIOTHINGS_BASE_URL, OUTPUT_DIR, or PORT as needed for your deployment. The repository documentation suggests standard MCP configurations; adjust env vars accordingly for your infrastructure.