---
id: mhctools
version: "3.31.5"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# mhctools — Python interface to MHC binding, presentation, immunogenicity, and antigen processing predictors

License: permissive · Maintenance: active · Downloads: 105.8K/mo

## What it is and what it does

mhctools wraps multiple published MHC prediction algorithms into a single Python interface, handling peptide-MHC binding affinity, surface presentation likelihood, stability, immunogenicity, antigen processing, and TCR recognition. It abstracts away the differences between underlying predictors (NetMHCpan, MHCflurry, NetCleave, Pepsickle, and others) and returns results as structured PeptideResult objects with consistent accessors for each prediction kind, or as pandas DataFrames for bulk analysis.

The package is designed for immunology and vaccine research workflows: scanning proteins for candidate epitopes, ranking peptides by MHC binding strength and percentile rank, predicting presentation likelihood across multiple HLA alleles, and handling multi-sample cohort predictions where each patient has a different HLA genotype. It supports both single-allele and haplotype-level predictions, with metadata describing whether each prediction kind is MHC-dependent and which MHC class (I or II) it applies to.

Use it for:

- Scan a protein sequence for immunogenic peptides that bind strongly to a patient's HLA alleles.
- Rank candidate neoantigen peptides by predicted MHC-I affinity and presentation likelihood for personalized cancer vaccine design.
- Predict TCR recognition of a peptide-MHC complex using paired CDR3 sequences and allele information.
- Generate flat DataFrames of peptide predictions across multiple samples with different HLA genotypes for cohort analysis.
- Combine multiple prediction kinds (affinity, stability, immunogenicity) to filter and prioritize epitope candidates.
- Integrate MHC predictions into a larger immunoinformatics pipeline alongside variant calling and protein annotation.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Unified Python interface to multiple MHC binding, presentation, immunogenicity, and antigen processing prediction tools, returning structured peptide results with affinity, percentile rank, and other prediction kinds.

Yes. mhctools is actively maintained, has low install friction, carries no known vulnerabilities, and uses a permissive license. It is the standard unified interface for MHC prediction in Python research workflows. Install it if you need to predict peptide-MHC binding, presentation, or immunogenicity; the main gotcha is that some wrapped predictors may require additional model downloads or environment setup beyond the base package.

## Install

pip install mhctools
uv add mhctools
poetry add mhctools

## Installing mhctools

Before you install: Low install friction; pure Python wheel with no compiled dependencies. Active maintenance: last release 34 days ago, repository at 103 stars, continuous commits. Requires Python >=3.9 and 7 runtime dependencies (numpy, pandas, varcode, pyensembl, sercol, mhcflurry, mhcgnomes), all standard scientific packages.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for research, clinical, and proprietary applications.

Quickstart:

from mhctools import NetMHCpan41

predictor = NetMHCpan41(alleles=["HLA-A*02:01", "HLA-B*07:02"])
results = predictor.predict(["SIINFEKL", "GILGFVFTL"])

for r in results:
    if r.affinity:
        print(f"{r.peptide} IC50={r.affinity.value:.1f}nM")

MHCflurry support requires running `mhcflurry-downloads fetch` after install to download model data.

Verify before relying:

- Whether all wrapped predictors (NetMHCpan, MHCflurry, NetMHCstabpan, etc.) are automatically available or require separate installation.
- Performance characteristics and typical runtime for protein scanning across different peptide lengths and allele counts.
- Whether TCR predictor support (NetTCR, Tulip) requires additional environment setup beyond the base install.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 105.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

MHC peptide binding prediction, HLA affinity prediction, immunogenicity scoring, antigen processing prediction, TCR binding prediction, MHC-peptide presentation, epitope prediction, immunoinformatics, epitope-prediction, vaccine-design

[View on SkillFed](https://skillfed.io/packages/mhctools) · [View on PyPI](https://pypi.org/project/mhctools/)