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.

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.

Does it help?

Not yet. In our benchmark Claude was no more accurate with this server than with a Python shell, and the server cost more. Taking files by path closed most of the cost gap, but not all of it.

Claude Opus 5.5 answered 38 questions 3 times each. Counting answers, as the chart does, the server got 110 of 114 right and a Python shell with piqtree and MAFFT got 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. In a pre-registered re-run of an unreleased commit that takes file paths (2026-10-18), the server cost 1.26 times as much (1.04 to 1.55) and got 36 of 38 questions right in every run against Python's 35: a tie, not a win.

The benchmark does not score support values; method, controls and other limitations are in benchmarks/agent_qa.

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"].

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 a replicate flipping. The server reports deterministic_across_processes: false. 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.
• Bootstrap only: no aLRT, approximate Bayes or UFBoot. Support is the nonparametric bootstrap (Felsenstein 1985), computed here because piqtree 0.8.3 runs bootstrap_replicates but does not expose the values.
• Cost is linear in replicates, each a full ML search. Capped at 200 taxa and 1000 replicates.
• 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.