phylokit-mcp

phylokit-mcp

phylokit-mcp is an MCP server that lets AI agents build maximum-likelihood trees with IQ-TREE 3 and align sequences with MAFFT.

[CI] [PyPI] [Python] [License] [DOI] [Glama]

A topology without support is not a result. infer_tree always runs a bootstrap and returns per-clade support. There is no flag to skip it.

Why the rule

A maximum-likelihood tree looks the same whether or not the data support it. Measured on alignments simulated from a known 7-taxon tree (JC, 100 replicates, seed 1):

At 60 sites the tree contains a clade (C,D,G) that does not exist and omits one that does (E,F,G). Both runs return a fully resolved Newick string of the same shape. Only the support values tell them apart, and the false clade is the lowest-supported one in the tree.

What it reports that a Newick string cannot

• Conflicting clades: groupings the data support at ≥0.70 that are absent from the reported tree. A support-annotated Newick string has nowhere to put them.
• fraction_resolved: the share of clades clearing 0.70. The headline number, before any single grouping is repeated as fact.
• Model runners-up with ΔAIC, not just a winner. On the 300-site alignment above, simulated under JC, the AIC winner is not JC (TPM2u and TPM2 tie), and several models, JC among them at ΔAIC 0.7, sit inside the conventional ±2 margin (seed=1, piqtree 0.8.3).
• Length versus evidence: n_parsimony_informative alongside n_sites. A 10,000-site alignment of near-identical sequences supports nothing.

Tools

Tools that take FASTA or Newick also take a file path (fasta_path, or trees_path for two trees), read by the server; a relative path resolves against the server's working directory.

The tests run real IQ-TREE and real MAFFT (no mocked engine), with 23 mutation checks and a real-process JSON-RPC handshake test.

Install

pip install phylokit-mcp

Requires Python 3.12+. IQ-TREE 3 comes through piqtree 0.8, which builds it into its wheel. align_sequences also needs the MAFFT binary on PATH, as does map_positions on unaligned input; the other tools work without it. Details: docs/INSTALL.md.

Configure your MCP client

{  "mcpServers": {    "phylokit": {      "command": "uvx",      "args": ["phylokit-mcp"]    }  }}

If uvx picks a Python older than 3.12, use "args": ["--python", "3.12", "phylokit-mcp"].

What the benchmark shows

Claude with the server was compared with Claude writing Python in an environment we set up with piqtree, cogent3 and MAFFT, on 38 phylogenetics questions, 3 runs each. A tie means the server matches that result without you building the environment. Questions right in every run, server against Python: Claude Haiku 5.5 34 against 37, Sonnet 5.5 37 against 35, Opus 5.5 36 against 35 (on the commit that takes file paths). None is separated (pre-registered; Holm-adjusted McNemar p = 0.75 on both Haiku and Sonnet). The server cost about the same as Python on Haiku and more on Sonnet (1.23×) and Opus (1.26×).

[Bar chart of 114 answers per setup (38 questions, 3 runs each). Claude alone: 114 declined. Read only: 76 right, 24 wrong, 12 declined, 2 invalid. Python, MAFFT and web: 113 right, 1 invalid. phylokit-mcp: 110 right, 4 wrong.]

The chart is the first Opus 5.5 run, on a release that took the data as text. Counting answers, the server got 110 of 114 right and Python 113; counting questions, 36 of 38 were right in every run against 37 (sign test p = 1). Per question the server took 6.0 times as long (95% CI 4.4 to 8.3) and cost 14.4 times as much (9.9 to 20.2), each a geometric mean of per-question ratios. Most of that cost was the model pasting the data file into tool calls; taking file paths (pre-registered re-run, 2026-10-18) brought it down to 1.26 times (1.04 to 1.55).

We wrote the questions and ran the benchmark ourselves; an outside re-run is welcome. The benchmark does not score support values; method, controls and other limitations are in benchmarks/agent_qa; the Haiku and Sonnet runs: 2026-10-20 re-run.

Reproducibility

Not bit-exact, in any setting: IQ-TREE reads the wall clock during its search, so the same request and seed can differ in the trailing digits of branch lengths and log-likelihood, and a support value can move: by about 0.05 (a replicate flipping) for the nonparametric bootstrap, and by no fixed bound for UFBoot2, whose replicates IQ-TREE draws inside the search (one clade moved 0.16 across six calls on one machine). The server reports deterministic_across_processes: false and the drift bound for the method used, null for UFBoot2. Compare trees with compare_trees and numbers with a tolerance, never by string equality. Measurements: docs/REPRODUCIBILITY.md.

Limitations

• Nucleotide and protein, no codon models. Pass sequence_type="protein" and a protein model (LG, WAG, …). The molecule type is declared, never sniffed: an A/C/G/T-only alignment is also valid protein (Ala/Cys/Gly/Thr), and a wrong guess returns a wrong tree, likelihood and support with no warning.
• Two bootstraps, no aLRT or approximate Bayes. The default is the nonparametric bootstrap (Felsenstein 1985), computed here, clades supported at 0.70; it is the only one that reports well-supported clades missing from the ML tree. support_method="ufboot" is IQ-TREE's UFBoot2 (Hoang et al. 2018), clades supported at 0.95.
• Nonparametric cost is linear in replicates, each a full ML search: on 89 taxa x 435 sites one replicate took 25-93 s, and 1000 UFBoot2 replicates 83 s. Capped at 200 taxa, 1000 nonparametric and 10000 UFBoot2 replicates. Every tool sends a progress notification every 15 s, so a client idle timeout does not abort a long call.
• Alignment is MAFFT --auto, single-threaded, and nothing else: no strategy choice, profile alignment or trimming; at most 200 sequences of 100,000 residues and 600 s. Gapped input is refused, not degapped. The tree tools refuse ragged input rather than align it.
• Unrooted trees. No rooting, dating or ancestral reconstruction.

License

GPL-2.0-only, because piqtree is GPL-2.0-only, which is incompatible with GPL-3.0. cogent3 is BSD.

If you publish results from this server, cite IQ-TREE 3, piqtree and (when it made the alignment) MAFFT, not this wrapper. The references are in CITATION.cff, and licensing and affiliation are in NOTICE.