Installation¶
This page covers supported BioMCP installation paths and verification checks.
After installation, the biomcp command should be available in your shell.
Option 1: Installer script¶
The installer downloads a prebuilt binary for your platform (Linux x86_64/arm64, macOS x86_64/arm64, Windows x86_64), verifies the SHA-256 checksum, smokes a destination-directory staging file, and atomically places biomcp in ~/.local/bin. It records standalone ownership in adjacent biomcp.install.json so update and uninstall cannot damage package-managed installs. It fails closed before replacement when verification fails, and a pending receipt makes interruption recovery deterministic.
The prebuilt Linux binaries carry a glibc 2.28 floor: they are built
in the manylinux_2_28 environment and run on RHEL 8, Debian 10, and
Ubuntu 20.04 onward. Linux older than that cannot run them; build
from source instead (Option 3). The PyPI wheels for Linux carry the
same floor.
The installer never edits shell startup files. If ~/.local/bin is missing from
PATH, it prints one export PATH=... command for you to copy. Install
sha256sum, shasum -a 256, or openssl dgst -sha256 before running it.
Pin a specific version:
Verify:
Option 2: PyPI package¶
Install the biomcp-cli package, then use the biomcp command in the rest of
this guide; the package name and the command name differ. To run BioMCP without
installing it, uvx needs --from because of that difference:
The wheels need Python 3.10 or later. An environment on an older Python — including the macOS system Python 3.9 — finds no matching distribution; create the environment with Python 3.10 or newer first.
The Linux wheels are tagged manylinux_2_28 and carry the same glibc
2.28 floor as the prebuilt Linux tarballs (RHEL 8, Debian 10, Ubuntu
20.04 onward). Older Linux cannot run them; build from source
instead (Option 3). A current pip is needed so the manylinux_2_28
tag resolves.
Verify:
Homebrew¶
Homebrew installs the macOS builds only, Apple silicon and Intel. There is no Linux formula; on Linux use the installer script, the PyPI package, or the Docker image.
Verify:
Option 3: Source build¶
From a local checkout:
Option 4: Docker image¶
Use the published GHCR image when you want BioMCP without a local Rust or Python toolchain:
docker run --rm ghcr.io/genomoncology/biomcp --version
docker run --rm ghcr.io/genomoncology/biomcp list
An image named without a tag resolves to latest, and a machine that already
pulled an older latest keeps running it until the next pull. Pull the image
before you run (docker pull ghcr.io/genomoncology/biomcp), or pin the release
you want, for example docker run --rm ghcr.io/genomoncology/biomcp:0.9.2
--version.
For stdio MCP clients, run the same image with serve and keep stdin open:
Pass provider keys from your shell when needed, for example -e ONCOKB_TOKEN or -e NCBI_API_KEY. Do not put secret values in documentation or checked-in client configs.
Post-install smoke checks¶
Environment notes¶
- Default output is markdown.
- Use
--jsonwhen a workflow needs structured output. - Add BioMCP to Codex, Claude Code, Claude Desktop, Cursor, Cline, VS Code, or another MCP client with the MCP clients guide.
- Optional API keys are documented in API keys.
Troubleshooting quick hits¶
- Command not found: ensure install location is on
PATH. - Checksum verification fails: retry the download; the installer intentionally refuses to install an archive without a valid checksum and a local
sha256sum,shasum, oropensslSHA-256 tool. - Normal source builds do not run or require
protoc; they consume committed AlphaGenome generated Rust. Maintainers regenerating that source need pinnedprotoc28.3 and can verify it without writing withscripts/regenerate-alphagenome-proto --check. - Network-related health failures: retry and inspect upstream API status.