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¶

curl -fsSL https://biomcp.org/install.sh | bash

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:

curl -fsSL https://biomcp.org/install.sh | bash -s -- --version 0.9.0

Verify:

biomcp --version

Option 2: PyPI package¶

uv tool install biomcp-cli
# or, inside an active Python environment:
# pip install biomcp-cli

Install the biomcp-cli package, then use the biomcp command in the rest of this guide. The package also keeps a small biomcp-cli compatibility command; it forwards to the sibling biomcp executable without changing command output or exit status.

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:

biomcp --version

Homebrew¶

brew tap genomoncology/biomcp
brew install biomcp

The separate genomoncology/homebrew-biomcp tap repository must exist before these commands can work; creating that tap is a one-time release prerequisite.

Verify:

biomcp --version

Option 3: Source build¶

From a local checkout:

make install
"$HOME/.local/bin/biomcp" --version

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

For stdio MCP clients, run the same image with serve and keep stdin open:

docker run --rm -i ghcr.io/genomoncology/biomcp serve

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¶

biomcp list
biomcp health --apis-only
biomcp search gene -q BRAF --limit 1

Environment notes¶

Default output is markdown.
Use --json when 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, or openssl SHA-256 tool.
Normal source builds do not run or require protoc; they consume committed AlphaGenome generated Rust. Maintainers regenerating that source need pinned protoc 28.3 and can verify it without writing with scripts/regenerate-alphagenome-proto --check.
Network-related health failures: retry and inspect upstream API status.