# BioMCP: One Binary and One Grammar for Biomedical Evidence > BioMCP is a Rust CLI and MCP server that puts roughly thirty biomedical sources behind a single command grammar, so researchers and AI agents can search, pivot and analyze without rebuilding filters for each API. **genomoncology/biomcp** — BioMCP: Biomedical Model Context Protocol - Repository: https://github.com/genomoncology/biomcp - Website: https://biomcp.org/ - Stars: 646 · Forks: 116 - Language: Rust - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/genomoncology-biomcp ## The identifier and API sprawl BioMCP is built to remove Biomedical search is fragmented along identifier lines. A gene lives in MyGene.info, UniProt, Reactome and QuickGO. A variant lives in MyVariant.info, ClinVar, gnomAD and OncoKB. A paper lives in PubMed, PubTator3, Europe PMC and PMC OA. The README frames the problem directly: BioMCP is "one CLI binary over a single command grammar" that reaches roughly thirty sources, so the same query shape works whether you are looking at a gene, a variant, a trial or an article. The audience is narrower than "everyone in bioinformatics". The README names researchers, clinicians and agents. The agent half matters: BioMCP is also a Model Context Protocol server, which means the same tools are exposed to Claude Code, Codex and Claude Desktop over stdio or HTTP. If you are building an LLM workflow that needs to cite ClinVar or pull a trial protocol, the alternative today is hand-writing a tool wrapper per source. BioMCP ships that wrapper layer already mapped. The design bet is that a shared grammar beats a shared schema. You do not get one unified JSON document across all sources; you get consistent verbs (search, get, discover, enrich, batch) applied to entities whose detail cards differ. That is a deliberate trade-off and it shows up the moment you compare a gene result to an article result. ## How the command grammar maps onto upstream providers The grammar is small enough to hold in your head. The README lays it out as search for discovery, get for focused detail, helper subcommands for cross-entity pivots, enrich for gene-set work, batch for parallel gets, and search all for counts-first orientation. Underneath, each entity is a fan-out. `search article`, for example, queries PubTator3 and Europe PMC, deduplicates PMID, PMCID and DOI identifiers, and can add a Semantic Scholar leg when your filters support it. Semantic Scholar is optional and gated behind the `S2_API_KEY` environment variable, so without that key you are searching two literature sources, not three. The README is explicit about that conditionality rather than implying all three always run. The pivot verbs are the interesting part. `article citations`, `article references`, `article recommendations` and `article entities` turn one known paper into an evidence map without you re-entering identifiers. On the variant side, `get variant "BRAF V600E" clinvar` pulls the ClinVar section for a named variant. The README also warns that the entity tables distinguish detail-card entities from search-only surfaces, precisely so agents do not synthesize `get` commands that have no backing provider. Architecturally this is a Rust binary (edition 2024) with a second binary target, `biomcp-cli`, and a Cargo workspace under `crates/`. HTTP caching is present in the dependency list through `http-cache-reqwest` and `cacache`, and retries through `reqwest-retry`, which suggests repeated queries against the same upstream are not re-fetched from scratch. The README does not document cache TTLs or eviction behaviour, so treat that as an implementation detail you can observe but not configure from the docs. ## Installing BioMCP and running a first cross-entity query The README's quick start claims a first useful query in under 30 seconds, and the path it recommends is the PyPI tool install through uv. Note the package name carefully: you install `biomcp-cli`, and the README carries an explicit warning that the `biomcp` PyPI package is unrelated to this project. ```bash uv tool install biomcp-cli biomcp health --apis-only biomcp skill list ``` The first command installs the `biomcp` binary into `~/.local/bin`. The second probes upstream APIs only, which is the fastest way to learn whether your network can reach the sources BioMCP depends on. The third lists the shipped worked examples, called skills, which are the closest thing to guided tutorials in the project. From there, a real query combines a gene and a disease across entities in one call: ```bash biomcp search all --gene BRAF --disease melanoma biomcp get gene BRAF pathways hpa ``` The first line is described as unified cross-entity discovery, returning counts-first orientation so you can see which entity types have material before drilling in. The second pulls the pathways and Human Protein Atlas sections for BRAF specifically. If you prefer not to install anything, the Docker image serves the same purpose: ```bash docker run --rm ghcr.io/genomoncology/biomcp --version docker run --rm -i ghcr.io/genomoncology/biomcp serve ``` The second form runs the stdio MCP server inside the container, which is how you would wire BioMCP into an MCP client without a local binary. For agent hosts, the README gives the registration step for Codex as `codex mcp add biomcp -- biomcp serve`, and for Claude Code as a plugin marketplace add followed by a plugin install. Both require the binary to exist first. ## The remote HTTP mode and what it changes about deployment Most MCP servers assume a local stdio process owned by one client. BioMCP also ships `serve-http`, which the README positions for shared or remote deployments: ```bash biomcp serve-http --host 127.0.0.1 --port 8080 ``` Remote clients then connect to `http://127.0.0.1:8080/mcp`, with probe routes at `GET /health`, `GET /readyz` and `GET /`. That read/write split matters operationally: you get liveness and readiness endpoints you can point a load balancer or a container orchestrator at, which a stdio-only server cannot offer. The example in the repository is a runnable client script, invoked as `uv run --script examples/streamable-http/streamable_http_client.py`. The README links a newcomer guide at biomcp.org/getting-started/remote-http/ rather than reproducing the full setup inline, so if HTTP transport is your use case, the site is the document to read, not the README. One honest gap: the README does not document authentication, TLS termination or rate limiting for `serve-http`. The default host is loopback, which is the safe default, but nothing in the README says what happens when you bind to a public interface. Treat that as something to verify against the remote HTTP guide before exposing the port. ## Where BioMCP is the wrong tool BioMCP is a network-first tool. Nearly every entity resolves through live public upstreams, and `biomcp health --apis-only` exists precisely because upstream reachability is a precondition. If your environment has no outbound access, or your compliance rules forbid querying third-party biomedical APIs, the CLI half is largely inert. The `study` commands are the exception the README calls out: they cover local query, cohort, survival, compare and co-occurrence workflows over downloaded cBioPortal-style datasets, with native terminal, SVG and PNG charts. That is genuinely local analysis, but it is scoped to data you already downloaded. Stability is the second boundary. The pyproject.toml carries the classifier "Development Status :: 4 - Beta", and the version string is 0.9.0.dev6 against a most recent tagged release of v0.8.25 on 2026-07-08. There is a visible gap between the dev version and the release line. If you need a frozen interface for a regulated pipeline, the command grammar is the thing most likely to move. There is also a discoverability trap the README itself flags. The PyPI name `biomcp` belongs to a different project. Anyone who installs by intuition rather than by reading the install section gets the wrong tool, and the failure will look like a missing binary rather than a naming mistake. The Homebrew path has a related precondition: the README states the separate `genomoncology/homebrew-biomcp` tap repository must exist before `brew tap genomoncology/biomcp` can work. ## How BioMCP differs from BioContextAI and MCPmed The adjacent projects in this space take a different cut. BioContextAI is a context layer for biomedical agents; MCPmed is a medical MCP server. Both sit in the same broad category, and both are worth comparing if you are choosing a server to attach to an agent. The difference in approach is packaging and surface area. BioMCP ships as a single Rust binary that is simultaneously a CLI and an MCP server, with the CLI usable on its own. That means a person can run `biomcp get gene BRAF pathways hpa` in a terminal and get the same result an agent would get through the tool call. The grammar is the product; MCP is one binding to it. Projects that are MCP-first tend to expose tools without a first-class human CLI, which makes debugging a failed agent call harder because you cannot reproduce it by hand. The second difference is the local analytics layer. BioMCP carries `study` commands and chart rendering for downloaded cBioPortal-style datasets, plus `biomcp enrich` for g:Profiler gene-set enrichment and `biomcp batch` for up to 10 focused `get` calls in one command. A pure retrieval server would stop at fetching. Whether that breadth is a strength or a scope problem depends on your workflow: it means one install covers retrieval and local cohort analysis, and it also means a larger dependency surface to audit. ## Licence, maintenance and the cost of keeping up The licence is MIT, declared in both Cargo.toml and pyproject.toml, and the container image carries the MIT identifier in its OCI labels. MIT is permissive: you can embed the binary in a commercial product, and the obligation is essentially attribution and inclusion of the licence text. Nothing in the README or the repository metadata suggests a separate commercial tier or a contributor licence agreement that would complicate that. This is a description of the licence terms, not legal advice; if you are redistributing the binary inside a regulated product, have counsel read the LICENSE file rather than this paragraph. Maintenance signals are mixed but concrete. The repository is not archived, and the last push was on 2026-09-10, which is recent. Releases, however, are spaced: v0.8.23 on 2026-06-11, v0.8.24 on 2026-06-24, v0.8.25 on 2026-07-08. The dev version in the working tree is 0.9.0.dev6, so a 0.9 line is in progress but untagged as of the last push. Upgrade cost is dominated by the grammar, not the packaging. The install paths are stable across binary, PyPI, Homebrew, Docker and source, and the binary is self-contained. The risk is that a minor bump changes a subcommand name or a section selector, which would break any script or agent prompt that embeds the grammar. If you pin, pin the binary version and keep `biomcp skill list` in your upgrade checklist, since the shipped skills are the workflows most likely to reflect grammar changes. ## Conclusion Adopt BioMCP if your work already moves between PubMed, ClinVar and ClinicalTrials.gov and you want one grammar instead of five API clients, or if you are wiring an MCP client such as Claude Code or Codex to live biomedical data. Skip it if you need a fully offline pipeline or a stable 1.0 interface; the project labels itself Beta and the PyPI version is 0.9.0.dev6. Before committing, run biomcp health --apis-only to see which upstreams answer from your network, confirm that pip install biomcp-cli resolves to the Rust binary and not the unrelated biomcp package, and check whether your agent host supports stdio MCP servers or needs biomcp serve-http on port 8080. ## FAQ ### What is the difference between the biomcp and biomcp-cli PyPI packages? The README warns that the `biomcp` PyPI package is unrelated to this project. Install `biomcp-cli` instead, which builds the Rust binary named `biomcp`. ### How do I install BioMCP with uv? The README's quick start uses `uv tool install biomcp-cli`, which places the `biomcp` binary in `~/.local/bin`. If that directory is not on PATH, the installer prints one command to add it and does not edit your shell startup files. ### How do I connect BioMCP to Claude Code or Codex as an MCP server? Install the `biomcp` binary first, then register the stdio server. For Codex the README gives `codex mcp add biomcp -- biomcp serve`; for Claude Code you add the hosted plugin marketplace and install the BioMCP plugin, which wires the client to `biomcp serve`. ### Can BioMCP run as a remote HTTP server instead of stdio? Yes. The README documents `biomcp serve-http --host 127.0.0.1 --port 8080`, with clients connecting to `http://127.0.0.1:8080/mcp` and probe routes at `GET /health`, `GET /readyz` and `GET /`. ## Sources - [genomoncology/biomcp on GitHub](https://github.com/genomoncology/biomcp) - [License: MIT](https://github.com/genomoncology/biomcp/blob/main/LICENSE) - [Project website](https://biomcp.org/) - [README](https://github.com/genomoncology/biomcp/blob/main/README.md) - [Releases](https://github.com/genomoncology/biomcp/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/genomoncology-biomcp