Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bpp-mcp guide me from raw sequence data to a validated BPP control file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that guides a researcher, including one new to BPP, from raw sequence data to a validated BPP control file that has passed a short test run. You talk to an AI assistant (Claude Code, Claude Desktop, Codex, Gemini CLI or any other MCP host); the assistant uses this server's tools to inspect your data, build the species tree, write and check the control file, and test it.
What it is not:
It does not run your analysis. It runs BPP for a few seconds to prove the control file and data load, then tells you the command to start the real run yourself.
It does not read BPP results or judge MCMC convergence.
It holds no BPP knowledge of its own. Syntax, defaults and checks come from
the bpp command-line tools it wraps (bpp-seqs, bpp-tree, bpp-lint,
bpp-docs, bpp), and the assistant is told to quote the manual rather
than answer from memory.
Linux or macOS, no root needed:
curl -fsSL https://raw.githubusercontent.com/bpp/bpp-mcp/main/install.sh | shThis installs uv into ~/.local/bin if you
don't have it (uv fetches a suitable Python if needed), installs the latest
bpp-mcp release with it, and runs bpp-mcp install-tools, which downloads
the tested releases of the BPP tools into ~/.local/share/bpp-mcp and checks
their SHA-256 hashes. Your shell startup files are not changed. At the end it
prints the command for registering the server with Claude Code or Claude
Desktop.
To do the same steps by hand, with any Python >= 3.10, install the release with the tool you prefer and then fetch the BPP tools:
pipx install https://github.com/bpp/bpp-mcp/releases/latest/download/bpp-mcp.tar.gz
bpp-mcp install-toolsuv tool install <that URL> and pip install <that URL> in a virtual
environment work the same way. bpp-mcp is not on PyPI yet, so
pipx install bpp-mcp does not work.
Run bpp-mcp install-tools again at any time; it only downloads what is
missing or out of date.
Prebuilt tool releases currently cover:
Tool | Linux x86_64 | Linux aarch64 | macOS arm64 | macOS x86_64 |
bpp | yes | yes | yes | yes |
bpp-seqs | yes | – | yes | yes |
bpp-tree | yes | – | yes | yes |
bpp-lint | yes | – | yes | yes |
bpp-docs | yes | – | yes | yes |
For anything missing, build the tool from its repository and put it on PATH
(or set BPP_MCP_<TOOL>, e.g. BPP_MCP_BPP_DOCS=/path/to/bpp-docs). The
check_environment tool reports what was found.
Related MCP server: MCP Sequence Simulation Server
The server is one command, bpp-mcp, speaking MCP over stdio. bpp-mcp install-tools prints its full path; use that path below in place of
/path/to/bpp-mcp.
The server only reads and writes inside one project directory:
BPP_MCP_ROOT, if set; otherwise the directory the host starts the server
in.
With BPP_MCP_PROJECTS_DIR set instead, the assistant asks which folder
under it to use (the set_project tool). This is for desktop apps, which
start servers in no particular directory.
The first thing the assistant does is call check_environment, which reports
the project directory. If it is not the folder holding your data, set
BPP_MCP_ROOT to that folder's absolute path.
claude mcp add --scope user bpp -- /path/to/bpp-mcpStart claude in the folder holding your data; that folder is the project
directory. /mcp inside a session shows whether the server is connected,
and claude mcp get bpp and claude mcp remove bpp inspect and remove it.
To share the server with everyone working in one repository, use
--scope project, which writes .mcp.json there. This registration was
tested with Claude Code on macOS.
Settings > Developer > Edit Config opens claude_desktop_config.json
(~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on
Windows; bpp-mcp itself supports only macOS and Linux). Add:
{
"mcpServers": {
"bpp": {
"command": "/path/to/bpp-mcp",
"env": { "BPP_MCP_PROJECTS_DIR": "/Users/you/bpp-projects" }
}
}
}Quit and reopen the app. Put each analysis in its own folder under that
directory. The app's log for the server is
~/Library/Logs/Claude/mcp-server-bpp.log.
codex mcp add bpp -- /path/to/bpp-mcpor in ~/.codex/config.toml:
[mcp_servers.bpp]
command = "/path/to/bpp-mcp"/mcp in Codex lists the server. Codex's documentation does not say which
directory the server starts in. If check_environment reports the wrong
project directory, add cwd = "/path/to/project" to the table or pass
--env BPP_MCP_ROOT=/path/to/project.
gemini mcp add -s user bpp /path/to/bpp-mcp(no -- before the command), or in ~/.gemini/settings.json:
{
"mcpServers": {
"bpp": { "command": "/path/to/bpp-mcp" }
}
}/mcp in Gemini CLI lists the server. As with Codex, the starting directory
is not documented; add "cwd": "/path/to/project" or
"env": { "BPP_MCP_ROOT": "/path/to/project" } if the project directory is
wrong.
The Codex and Gemini entries follow those hosts' documentation as of October 2026 and have not been tried by hand.
Nothing in the server depends on the host or the model. Register the same
bpp-mcp command with another host and point it at the same project
directory; the data, tree and control files are ordinary files there, and
any assistant can pick up where another stopped by linting the control file
again.
The usual path is: check the installation, inspect the data, convert it, build the tree, make the control file, lint it until valid, test it, and hand you the run command.
Tool | What it does |
| Finds the BPP tools, checks their versions, reports the project directory. |
| Chooses the project folder (only with |
| Summarises your data files and Imap without changing anything. |
| Converts alignments, BAM/CRAM or gVCF data to a BPP sequence file. |
| Tiles a genome into candidate loci when you have no BED file. |
| Writes a sequence file with a subset of the loci, e.g. for a trial run. |
| Builds the species or guide tree from joins such as |
| Reads a tree you already have (Newick, or an old control file). |
| Writes the control file for an A00, A01, A10 or A11 analysis, with priors derived from the data. |
| Changes one keyword in a control file and lints it again. |
| Validates a control file and checks it against its data files. |
| Shows, then applies, the fixes that bring a BPP 2.x/3.x file up to date. |
| Quote the BPP manual. |
| Explains a lint diagnostic code. |
| Runs BPP briefly on a copy of the control file to prove it loads. |
| Gives you the command and folder for the real run. Does not start it. |
Three prompts start the common jobs (in Claude Code they appear as slash
commands): novice_setup, upgrade_old_file and check_my_ctl. Two
resources are available to hosts that load them: bpp://manual/{keyword}
and bpp://examples/{name} (the example control files shipped with BPP and
bpp-lint; bpp://examples lists them).
Whatever a tool returns is sent to the AI model your host uses, which is usually a service run by a third party. The server is built so that your sequences are not:
Tools return summaries: counts, file and sample names, species names, per-locus statistics, lint diagnostics, control-file text, and BPP's screen output from the test run.
Any run of more than 30 nucleotide characters in a result is replaced by a note saying how many characters were removed, and long lists and strings are cut, with a note saying so.
The tests check, for every tool, that no sequence from the test data appears in its output.
Sample names, species names, file names and locus coordinates do reach the
model. The server itself makes no network connections while serving; only
bpp-mcp install-tools downloads anything. The assistant can still read
files itself if your host gives it its own file access, which this server
does not control.
python3 -m venv .venv && .venv/bin/pip install -e '.[test]'
.venv/bin/bpp-mcp install-tools
.venv/bin/pytest -qBPP-MCP-BUILD.md is the specification and claude_next.md the current
status. To release, set __version__, tag vX.Y.Z and push the tag; the
release workflow builds, tests and publishes. Its "Run workflow" button
does everything except publish.
Licence: AGPL-3.0-or-later.
Build the species (or guide) tree from a join formula (bpp-tree).
Writes PREFIX.stree (the species&tree block, with individual counts taken
from the Imap, plus any migration block) and PREFIX.nwk. Pass PREFIX.stree
to make_control_file as stree_file.
joins: comma-separated joins, each 'X+Y' or 'X+Y=name', e.g.
'chimp+bonobo=pan, pan+human, gorilla+pan_human'. A label like A_B
refers to the clade of A and B. Tip names are the Imap's species names.
Ask the user for the tree (or guide tree for delimitation); do not
invent one.
migration (MSC-M): bands 'SRC->DST, ...'. Mutually exclusive with
introgression. The control file then also needs a wprior.
introgression (MSC-I): events 'DONOR->RECIP phi=0.1, ...'. The control
file then also needs a phiprior.
Look up those priors with lookup_docs; lint_control_file reports what is
missing.
Read in the report: newick, taxa, species_counts,
species_and_tree_block, and warnings (e.g. ROOT_AUTO_JOINED: two
clades were joined at the root automatically) and errors.
server.diagram is an ASCII drawing of the tree. ALWAYS show the user the
diagram and ask them to confirm the topology before going on.
Inputs: imap (required), joins (required), out_prefix (required), migration, +1 more.
Check that the BPP command-line tools are installed and new enough.
Call this FIRST in every session, before any other tool. It runs
<tool> --version for bpp-seqs, bpp-tree, bpp-lint, bpp-docs and bpp.
Output:
ready: true only when every tool is found and new enough AND a project
directory is set. If false, read problems and help the user fix them
before doing anything else; tell them the exact install_hint command.
tools.<name>: found, path, version, minimum_version, ok, and
problem / install_hint when something is wrong. Most tools are
installed by the user running bpp-mcp install-tools in a terminal
(no root needed); you cannot run it for them.
project_root: the only directory the tools can read or write. Every
path you pass to other tools is relative to it. If it is null, no
project is set: ask the user which project folder to use and call
set_project (if available), or explain that the host configuration must
set BPP_MCP_ROOT.
Inputs: no named parameters.
Convert the inspected data into BPP input files (bpp-seqs).
Writes PREFIX.txt (the BPP seqfile), PREFIX.imap, PREFIX.stats.tsv and
PREFIX.loci.tsv, where PREFIX is out_prefix relative to the project.
Use the same files (globs allowed) and imap as inspect_data.
Options, all passed to bpp-seqs unchanged:
phasing (BAM/CRAM and gVCF input only): iupac | split | haploid | vcf.
Ask the user whether their diploid data are phased; for vcf also give
phased_vcf. It does not apply to alignments.
reference: designate the reference FASTA explicitly.
Locus filters (bpp-seqs defaults apply when omitted): min_length,
max_missing, min_snps, keep_invariant; read-based calling:
min_bq, min_mq, min_dp, het_freq.
overwrite: existing outputs are refused unless true. Ask the user first.
Read in the report: summary.n_loci_passed (also server.nloci) is the
nloci value for make_control_file; summary.failure_reasons and loci[]
say which loci were dropped and why; output_files names the files
written. Tell the user how many loci passed. Next: build_species_tree.
Inputs: imap (required), files (required), out_prefix (required), min_bq, +11 more.
Long explanation of a bpp-lint diagnostic code, e.g. 'BPP101' or '101'.
Use it to explain a lint_control_file diagnostic to the user in plain
language. Returns code and text.
Inputs: code (required).
Inspect the user's data files without changing anything (bpp-seqs --dry-run).
Call after check_environment, on whatever the user has: aligned loci
(FASTA/PHYLIP/NEXUS, one or many per file), BAM/CRAM, gVCF, BED, a reference
FASTA, and the Imap (sample -> species table). File types are detected from
content. files may contain glob patterns relative to the project, e.g.
["loci/*.fasta"].
Read in the report:
workflow (e.g. fasta2bpp) and ready_to_run: whether convert_data can
run with these inputs.
missing[]: inputs still needed (often the Imap). Ask the user for them.
cross_validation.issues: mismatches between files, e.g. samples in the
data but not the Imap. Explain them to the user before converting.
files_provided[]: per-file type and counts; server.file_types counts
the types.
Next: convert_data with the same files and Imap.
Inputs: files (required), imap.
Validate a control file (bpp-lint --json --check-priors) and check it against its data.
Call after make_control_file and after every change. Loop until
server.status is "valid": fix each error (with set_keyword, or by
remaking the file with make_control_file and the corrected arguments),
then lint again.
Read in the result:
server.status: "valid" only if bpp-lint reports no errors AND the
temporary server.data_checks found none. Use this, not report.status.
report.diagnostics[]: each has code, severity, message,
suggestion, suggested_fix. Use explain_diagnostic(code) to explain
one to the user.
report.prior_check: priors compared with estimates from the data.
server.data_checks.issues[] (temporary, until bpp-lint checks these
itself): missing data files, nloci larger than the data, sequence tags
with no Imap line, Imap species that differ from the tree, phase digit
count, speciesdelimitation with the wrong number of arguments.
A valid lint does not prove BPP will run: smoke_test next.
Inputs: ctl (required).
The BPP manual's entry for one control-file keyword, quoted verbatim (bpp-docs).
Use this instead of your own knowledge whenever you state BPP syntax,
defaults, allowed values or keyword dependencies, and quote it to the user.
keyword is a control-file variable such as 'thetaprior', 'phase' or
'speciesdelimitation'.
Read in the report: found; syntax, values, default,
dependencies, description, and text (the whole section). If
found is false, use search_docs.
Inputs: keyword (required).
Create a BPP control file (bpp-lint --template --suggest-priors).
Never write a control file yourself; use this, then lint_control_file.
analysis: A00 = estimate parameters on a fixed species tree;
A01 = estimate the species tree; A10 = species delimitation on a fixed
guide tree; A11 = joint species delimitation and species tree. Ask the
user, explaining the choices in plain language.
seqfile, imapfile: from convert_data (PREFIX.txt, PREFIX.imap).
stree_file: from build_species_tree (PREFIX.stree). nloci: from
convert_data's server.nloci. out: the control file to write.
Data paths are written relative to the control file's folder.
phase: for unphased diploid data, one digit per species in
species&tree order (look up 'phase' with lookup_docs and ask the user).
thetaprior, tauprior: leave unset to use priors derived from the
data (inverse-gamma, alpha = 3); set only if the user asks.
nsample, burnin, sampfreq, seed: chain settings; template
defaults apply when unset. Discuss chain length with the user.
extra: any other keywords as {"keyword": "value"}, e.g.
{"wprior": "...", "threads": "..."}. Each name is checked against the
manual's keyword list. Look up the syntax with lookup_docs first.
overwrite: an existing file is refused unless true. Ask the user.
Returns the file's text and path. server.workarounds_applied lists
patches for known bpp-lint bugs. Next: lint_control_file.
Inputs: out (required), nloci (required), seqfile (required), analysis (required), +12 more.
Make a BED file of candidate loci by tiling a genome into windows (bpp-seqs windows).
Use when the user has BAM/CRAM or gVCF data but no BED file saying which
regions are the loci (inspect_data then lists a BED under missing).
input is anything holding chromosome names and lengths: the reference
FASTA, a BAM/CRAM or a VCF/gVCF. out is the BED file to write; pass it
to inspect_data and convert_data with the other files.
Ask the user for the locus size and spacing; do not choose them yourself. All options are passed to bpp-seqs unchanged:
window_size: locus length in bp. step: distance between window
starts (default: window_size, so windows do not overlap).
min_spacing: least distance in bp between kept loci on a chromosome.
n_loci: sample this many windows at random (seed fixes the sample);
omit to keep them all.
include_chrom / exclude_chrom: chromosome names. autosomes_only:
skip sex chromosomes, mitochondria and unplaced contigs (by name).
skip_edges: drop this many bp at both ends of each chromosome.
exclude_regions: a BED file of intervals to avoid.
overwrite: an existing file is refused unless true. Ask the user.
Read in the report: n_windows_emitted (loci written) and the counts
before it, which show what each filter removed. Next: inspect_data.
Inputs: out (required), input (required), window_size (required), seed, +9 more.
Read a species tree the user already has (bpp-tree --read).
Use instead of build_species_tree when the user has a tree file: a Newick (or extended Newick with introgression), a species&tree block, or an old control file containing one. Migration and introgression in the file are recovered too.
imap: the Imap from convert_data; fills in the individual counts.
Without it the block has '?' for the counts and cannot be used yet.
out_prefix: also write PREFIX.stree and PREFIX.nwk, for
make_control_file's stree_file. Give it together with imap.
Read in the report: status, newick, taxa, species_and_tree_block,
individual_counts_filled, migration, introgression, warnings and
errors. server.diagram is an ASCII drawing of the tree: ALWAYS show
it to the user and ask them to confirm it is the tree they meant.
server.stree_file is set when out_prefix was given.
Inputs: path (required), imap, out_prefix.
How the user starts the full analysis themselves. Does NOT run BPP.
Call last, once lint_control_file reports server.status "valid" and smoke_test did not fail. This server never starts the real run, which can take hours or days; give the user the command to run in their own terminal or job script.
Read in the result:
directory: the control file's folder (absolute). BPP must be started
from it, because the data paths in the file are relative to it.
command: the BPP command line, with the full path of the same bpp
binary smoke_test used.
shell: both as one line to paste into a terminal.
jobname, threads: the file's current values (null if unset). Output
files are named from jobname. Look up 'threads' with lookup_docs
before advising on it, and change it with set_keyword.
notes: what to tell the user about long runs and clusters.
Inputs: ctl (required).
Ranked full-text search of the BPP manual (bpp-docs --search).
Use for concepts rather than single keywords, e.g. 'migration prior',
'unphased diploid', 'species delimitation algorithm'. Returns the best
matching sections with heading, score and snippet. Follow up with
lookup_docs for a keyword, and quote the manual to the user.
Inputs: query (required).
Change one keyword in a control file, then lint the file again.
Use this for every edit to an existing control file; never edit one by hand. Look up the keyword's syntax with lookup_docs first, and ask the user before changing a scientific choice.
keyword: a control-file keyword, checked against the manual's list.
value: everything after the =, on one line, e.g. "200000" for
nsample or "invgamma 3 0.002" for thetaprior.
The keyword's line is replaced where it stands (layout and comments are kept); a keyword the file does not have yet is added at the end. A value that spans several lines in the file (such as species&tree) is refused: remake the file with make_control_file instead.
Returns the lint_control_file result for the edited file, plus
server.changed (keyword, old, new; old is null if it was unset).
Read server.status as usual, and run smoke_test again once it is "valid".
Inputs: ctl (required), value (required), keyword (required).
Run BPP briefly to prove it accepts the control file and loads the data.
Call after lint_control_file reports server.status "valid". Runs a copy of
the file with a short chain (nsample, burnin) in a scratch folder that
is deleted afterwards, from the control file's folder (as the real run
will be). The results are NOT an analysis; never report them as findings.
Read in the result:
ok: true if BPP finished; false if it failed (see error_line, BPP's
fatal message, and output_tail); null if still running at timeout_s
without an error, which means BPP read the file and data and started
the MCMC.
Only when lint is valid AND ok is not false is the file ready. Then call
run_command to tell the user how to run the full analysis.
Inputs: ctl (required), burnin, nsample, timeout_s.
Write a new BPP seqfile holding a subset of the loci of an existing one (bpp-seqs extract).
Use to make a small data set for a trial run, or to drop or keep
particular loci. seqfile is a PREFIX.txt from convert_data. Writes
out_prefix.txt, plus .imap and .loci.tsv when the input has them next to
it. The original files are not changed.
Selection (at least one; passed to bpp-seqs unchanged):
first / last: the first or last N loci. range: 1-based positions
such as "1-50" or "1-10,41-50". These three add together.
loci: locus names. chrom: loci from this chromosome (needs the
.loci.tsv). min_sites / max_sites: by alignment length.
Different kinds of selection combine with AND. invert: keep the loci
that do NOT match.
imap: use this Imap instead of the one next to the seqfile.
overwrite: existing outputs are refused unless true. Ask the user.
Read in the report: n_loci_input, n_loci_kept (also server.nloci:
the nloci value for make_control_file with the new seqfile) and
output_files. Next: make_control_file with the new seqfile, or
set_keyword for seqfile and nloci on an existing control file.
Inputs: seqfile (required), out_prefix (required), imap, last, +8 more.
Bring a control file written for BPP 2.x/3.x up to current syntax (bpp-lint --diff / --fix).
For users who arrive with an old control file. Call first with
apply=false: nothing is written, and server.upgrade.diff shows the
changes bpp-lint can make by itself (renamed keywords, old value
formats). Show the user the diff. Only after they agree, call again with
apply=true: the file is rewritten in place and the original is kept as
.bak.
Returns the lint_control_file result for the file as it now stands (after
the rewrite when apply=true), plus server.upgrade:
fixes_available: false means bpp-lint has nothing to rewrite.
diff: unified diff of the automatic fixes.
applied, and backup (the .bak file) when applied.
Automatic fixes are only part of an upgrade: errors left in
report.diagnostics need a decision from the user. Make those changes
with set_keyword, then lint again until server.status is "valid".
Inputs: ctl (required), apply.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
Each tool maps to a distinct BPP pipeline stage: environment check, data inspection/conversion, tree building/reading, control-file creation/editing/linting, documentation lookup/search, smoke testing, and run-command generation. The closest overlap is inspect_data vs convert_data, but the dry-run versus write distinction is made explicit in the descriptions. No tools appear to do the same thing.
All tool names use snake_case and follow a mostly consistent verb_noun or verb_object pattern (check_environment, inspect_data, convert_data, build_species_tree, lint_control_file, run_command). The only minor variant is smoke_test as a compound noun, but it still fits the readable convention and does not disrupt predictability.
The server has 16 tools, slightly above the typical 3-15 range, but each corresponds to a real, non-redundant step in the BPP preparation workflow. Given the domain's complexity (data conversion, BED creation, subsetting, tree handling, control-file lifecycle, docs, smoke test, and run command), the count is reasonable rather than bloated.
The surface covers the core lifecycle from environment check through data conversion, tree building, control-file creation/linting, smoke testing, and final run-command generation. However, check_environment references set_project when no project root is configured, yet that tool is absent, leaving a configuration dead end; post-run BPP result parsing is also outside the surface.
Validated molecular biology tools: cloning, primers, CRISPR, Sanger, alignment, qPCR, phylogenetics
Run protein folding, docking, design and sequence analysis tools, and read their results.
Hosted DNA/RNA/protein tools: primers, oligos, PCR, cloning, CRISPR, alignment, batch & pipelines.
Stateless advisor + validator for Conducted Development: kickoff, artifact validation, rule checks.
