# Proteinmpnn

> Skill for inverse folding — designing amino acid sequences for a given protein backbone structure. Use this skill when a user wants to design sequences for a PDB structure, score sequences against a structure, design symmetric oligomers with tied positions, fix specific residues while redesigning others, or use evolutionary (PSSM) guidance. Also trigger when the user mentions ProteinMPNN, inverse…

- **Type:** Skill
- **Install:** `agentstack add skill-naity-fm4life-proteinmpnn`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [naity](https://agentstack.voostack.com/s/naity)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [naity](https://github.com/naity)
- **Source:** https://github.com/naity/FM4Life/tree/main/skills/proteinmpnn

## Install

```sh
agentstack add skill-naity-fm4life-proteinmpnn
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ProteinMPNN: Inverse Folding for Protein Sequence Design

## Overview

ProteinMPNN designs amino acid sequences for a given protein backbone structure. It is the sequence design step in the modern protein design pipeline:

```
RFdiffusion (backbone) → ProteinMPNN (sequence) → AlphaFold2 (validation)
```

Given a backbone PDB, ProteinMPNN outputs sequences that are predicted to fold into that structure. It can design multiple chains simultaneously, lock specific residues, enforce symmetry, and score existing sequences.

**Core capabilities:**
- **Sequence design** — generate sequences for any protein backbone
- **Scoring** — evaluate how well a given sequence fits a structure
- **Fixed positions** — lock active site or interface residues
- **Tied positions** — enforce symmetric sequences across chains (homooligomers)
- **Amino acid bias** — favor or disfavor specific amino acids globally or per-residue
- **PSSM guidance** — incorporate evolutionary information

## Installation

```bash
# Create conda environment
conda create --name mlfold python=3.9
conda activate mlfold

# Install PyTorch with CUDA
conda install pytorch torchvision torchaudio cudatoolkit=11.3 -c pytorch

# Clone repository
git clone https://github.com/dauparas/ProteinMPNN.git
cd ProteinMPNN
```

No pip install — run directly from the repository.

## Model Checkpoints

| Checkpoint | Use case |
|---|---|
| `v_48_020.pt` | Default; best general-purpose model |
| `v_48_030.pt` | Latest checkpoint |
| `v_48_010.pt` | Intermediate checkpoint |
| `v_48_002.pt` | Early checkpoint |
| `soluble_model_weights/v_48_020.pt` | Soluble proteins only |
| `ca_model_weights/v_48_020.pt` | CA-only backbone (faster) |

Default: `v_48_020.pt`. Use `--use_soluble_model` or `--ca_only` to switch model families.

## Core Workflows

### 1. Minimal monomer design

```bash
python protein_mpnn_run.py \
  --pdb_path input.pdb \
  --pdb_path_chains "A" \
  --num_seq_per_target 8 \
  --sampling_temp "0.1" \
  --out_folder results/
```

Generates 8 sequences for chain A at temperature 0.1. Output: `results/seqs/input.fa`.

### 2. Multi-chain complex

Parse first, then design:

```bash
# Step 1: parse PDB directory to JSONL
python helper_scripts/parse_multiple_chains.py \
  --input_path pdbs/ --output_path parsed.jsonl

# Step 2: assign which chains to design
python helper_scripts/assign_fixed_chains.py \
  --input_path parsed.jsonl \
  --output_path chain_ids.jsonl \
  --chain_list "A B"

# Step 3: run design
python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --chain_id_jsonl chain_ids.jsonl \
  --num_seq_per_target 2 \
  --sampling_temp "0.1" \
  --out_folder results/
```

### 3. Fixed positions (lock active site)

```bash
# Create fixed positions dict
python helper_scripts/make_fixed_positions_dict.py \
  --input_path parsed.jsonl \
  --output_path fixed.jsonl \
  --chain_list "A" \
  --position_list "1 2 3 45 46 47"

# Run with fixed positions
python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --fixed_positions_jsonl fixed.jsonl \
  --num_seq_per_target 4 \
  --sampling_temp "0.1" \
  --out_folder results/
```

To specify *designable* positions instead (all others fixed): add `--specify_non_fixed`.

### 4. Homooligomer / symmetric design

```bash
# Tie equivalent positions across all chains
python helper_scripts/make_tied_positions_dict.py \
  --input_path parsed.jsonl \
  --output_path tied.jsonl \
  --homooligomer 1

python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --tied_positions_jsonl tied.jsonl \
  --num_seq_per_target 4 \
  --sampling_temp "0.2" \
  --out_folder results/
```

All chains get the same sequence. Works for C2, C3, C6, etc.

### 5. Score existing sequences

```bash
python protein_mpnn_run.py \
  --pdb_path structure.pdb \
  --path_to_fasta sequences.fasta \
  --score_only 1 \
  --out_folder results/
```

Reports `score` (negative log probability) and `seq_recovery` for each sequence.

### 6. Amino acid bias (avoid cysteine)

```bash
python helper_scripts/make_bias_AA.py \
  --output_path bias.jsonl \
  --AA_list "C" \
  --bias_list "-1.0"

python protein_mpnn_run.py \
  --jsonl_path parsed.jsonl \
  --bias_AA_jsonl bias.jsonl \
  --omit_AAs "C" \
  --out_folder results/
```

Use `--omit_AAs "C M"` to fully exclude amino acids.

## Key Parameters

| Parameter | Default | Description |
|---|---|---|
| `--num_seq_per_target` | 1 | Sequences to generate per structure |
| `--sampling_temp` | — | Sampling temperature (0.1–0.3 typical; higher = more diverse) |
| `--model_name` | `v_48_020` | Model checkpoint |
| `--use_soluble_model` | — | Use soluble-only model weights |
| `--ca_only` | — | Use CA-only model (faster, less accurate) |
| `--backbone_noise` | 0.0 | Gaussian noise on atom coordinates |
| `--batch_size` | 1 | GPU batch size |
| `--seed` | 0 (random) | Random seed for reproducibility |
| `--save_score` | 0 | Save scores to NPZ |
| `--save_probs` | 0 | Save AA probabilities to NPZ |
| `--score_only` | 0 | Score without generating |
| `--omit_AAs` | — | Exclude amino acids (e.g. `"C M"`) |

## Output Format

```
results/
├── seqs/
│   ├── protein_name.fa          ← designed sequences (FASTA)
├── scores/                      ← NPZ score files (if --save_score 1)
└── probs/                       ← probability NPZ files (if --save_probs 1)
```

**FASTA header format:**
```
>native, score=-0.45, global_score=-0.42, seq_recovery=1.0, model_name=v_48_020
>T=0.1, sample=1, score=-0.48, global_score=-0.46, seq_recovery=0.87
```

- **score** — negative log probability over designed residues (lower = better fit)
- **global_score** — negative log probability over all residues
- **seq_recovery** — fraction of positions that match the input sequence

## Scripts

- `scripts/design.py` — design sequences from PDB files; see `scripts/design.py --help`

## Resources

- **GitHub:** https://github.com/dauparas/ProteinMPNN
- **Paper:** Dauparas et al., Science 2022 — https://doi.org/10.1126/science.add2187

## References

- `references/cli-reference.md` — full CLI parameter reference, all input/output formats, PSSM guidance, conditional probabilities

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [naity](https://github.com/naity)
- **Source:** [naity/FM4Life](https://github.com/naity/FM4Life)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-naity-fm4life-proteinmpnn
- Seller: https://agentstack.voostack.com/s/naity
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.