danielLuo2/bioharbor

Run real bioinformatics from your AI agent. Reliable, reproducible, on your own GPUs.
> 🧪 Alpha (v0.1). Sequence tools, homology search (MMseqs2) and structure prediction
> (ESMFold, validated on RTX 5090) work. Feedback welcome — see the roadmap.
BioHarbor is an MCP server that lets AI agents such as
Claude, Cursor and Codex execute bioinformatics tools — not just look things up. Agents
ask for an analysis; BioHarbor validates the input, schedules it on a GPU with room, records
exactly how it ran, and hands back a compact, agent-readable summary.
## Why another bio MCP server?
Most bio MCP servers wrap databases (UniProt, PDB, PubMed…). Use them — BioHarbor
complements them by running the compute:
| | Database MCP servers | BioHarbor |
| Runs real analyses (search, fold, cluster) | ❌ | ✅ |
| Validates inputs before burning GPU time | ❌ | ✅ |
| GPU-aware queue, polite on shared GPUs | ❌ | ✅ |
| Long jobs return a jobid instead of timing out | ❌ | ✅ |
| Compact summaries + files on disk (saves tokens) | ❌ | ✅ |
| Provenance for every run, export to a pipeline | ❌ | ✅ (export: planned) |
## Quick start
bash
pip install bioharbor
bioharbor doctor # checks Python, GPUs, workspace, tools
bioharbor setup-db swissprot # reference database for searchhomologs (needs MMseqs2)
bioharbor install # shows how to connect Claude, Cursor or Codex
For structure prediction on a GPU: pip install "bioharbor[esmfold]" — see
docs/gpu-setup.md (RTX 50xx needs a CUDA 12.8+ PyTorch).
### Connect your agent
BioHarbor is a standard MCP server, so it works with any MCP client. One command sets up
the popular ones (it writes an absolute path, so GUI apps find it even outside your venv):
| Client | Set up |
| Claude Code | claude mcp add bioharbor -- bioharbor serve |
| Claude Desktop | bioharbor install claude-desktop --write, then restart the app |
| Cursor | bioharbor install cursor --write, or |
| Codex (CLI, IDE extension, app) | codex mcp add bioharbor -- bioharbor serve, or bioharbor install codex --write |
| Biomni (Stanford's biomedical agent) | agent.addmcp(...); see docs/use-with-biomni.md |
| Anything else | run bioharbor serve (stdio) or bioharbor serve --http (Streamable HTTP) |
Long-running tools return a jobid within ~20 s instead of blocking, so they stay
within every client's tool-call timeout.
Step-by-step setup (local or on a GPU server,
with troubleshooting): docs/connect-clients.md.
Then ask your agent something like:
> Find the longest ORF in this contig, translate it, search Swiss-Prot for homologs and
> predict its structure. Which regions are low confidence?
### Use it without an agent
Every tool is also a CLI command, with identical behaviour:
bash
bioharbor tools list
bioharbor run findorfs sequence=@contig.fa minaa=100 --brief # human-readable
bioharbor run seqstats sequence=MKTAYIAKQRQISFVKSHFSRQ
bioharbor jobs
### Shared GPU server
GPUs on a lab server, agent on your laptop? Run BioHarbor on the server and reach it
through an SSH tunnel; no extra port is opened on the server:
bash
# on the GPU server
bioharbor serve --http --host 127.0.0.1 --port 8765