io.github.chowdhurylab-studio/ipro-agent
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., "@io.github.chowdhurylab-studio/ipro-agent redesign my enzyme to prefer C12 over C14 at residues 110, 113, 117"
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.
ipro-agent
An independent, agent-drivable reimplementation of the published IPRO procedure (Iterative Protein Redesign and Optimization).
Unsupported research code, maintained by the Chowdhury Lab; please use GitHub issues. It implements a method published by the Maranas group (Penn State), cited under Citing. It is not their software and is not endorsed by them. None of their code is in it.
IPRO as published is a suite of programs wired to specific case studies: the molecules, the design positions and the objective live in a per-case Python input deck. This repo keeps the machinery and replaces the wiring with a declarative problem statement, so the same optimizer can be pointed at an arbitrary protein and an arbitrary stated goal, by a person or by an LLM agent.
You give it:
a goal in plain language, mapped to one of five objectives;
structures of the interacting partners (protein, peptide, small molecule, transition-state analogue);
the positions where mutation is allowed, and the amino acids allowed at each.
It writes the rotamer-selection MILP that encodes those constraints, then iterates: perturb → choose optimal rotamers → dock → relax → accept or reject on energy. Out comes a design sequence, the per-iteration energies, and an ensemble of the best designs.
Quick start
Two lines, if you want to drive it from an agent. Install it, then point your MCP client at it:
pip install ipro-agent{"mcpServers": {"ipro-agent": {"command": "ipro-agent-mcp"}}}Then ask your agent to run ipro_doctor, which reports what resolved. On a
bare pip install it reports PyMOL missing: ipro_validate,
ipro_inspect_structure and ipro_goals still work, so the agent can read a
structure and check a spec, while ipro_score and ipro_milp refuse in those
words rather than guessing. PyMOL is the one dependency pip cannot supply, so
for a design install it from conda-forge and point command at that
environment's ipro-agent-mcp:
conda create -n ipro-agent -c conda-forge pymol-open-source python=3.12
conda activate ipro-agent
pip install ipro-agentSet IPRO_REPO to a checkout as well if you want the server to serve its own
documents rather than tell the agent where to fetch them.
One command, if you want the example and the documents too:
bash scripts/bootstrap.shThat creates the environment, reports what resolved, runs the test suite and the shipped example, and prints the exact commands and MCP config with your own paths filled in. Safe to re-run; deletes nothing.
What using it looks like: resolve the positions, prove the constraint reached the solver, run, and read the refusal. Reconstructed rather than recorded, from real output of the shipped example. More worked prompts, with what each one produces.
By hand instead. The install step is not optional: rotamers come only from
PyMOL's mutagenesis wizard, and pymol-open-source is conda-only, so
pip install alone cannot give you a working design pipeline:
conda env create -f environment.yml && conda activate ipro-agentThen check what resolved. Everything below runs from the repo root; nothing needs installing the package itself:
python3 scripts/doctor.py --require pymolpython3 -m ipro_agent validate examples/ompf_pore/spec_smoke.yamlpython3 -m ipro_agent run examples/ompf_pore/spec_smoke.yaml --run-dir runs/smokepython3 -m ipro_agent status runs/smokeWhat that run produces, so you can tell a working install from a real result:
with the shipped seed it accepts 3 iterations and reports zero mutations. The
native residues win at those four positions because no reference-energy term
offsets the packing bias against large side chains, and the run says so in its
notes. That is a successful smoke test rather than a design. For a run that
does mutate, see examples/ompf_pore/spec_full.yaml (25 positions,
~85 s/iteration) or set goal_options.reference_energies.
Related MCP server: Rosetta MCP
For agents
Clone the repo, create the conda environment above, open it with an agent and
ask in plain language: "redesign this thioesterase to prefer C12 over C14, you
may change residues 110, 113 and 117". The skill at
.claude/skills/ipro-agent/SKILL.md loads
itself from its description. Beyond that one environment step there is nothing
for the agent to configure; it should run scripts/doctor.py first and report
the mode it finds.
To read it yourself, it is the operating manual: goal selection, spec format, encoding user constraints into the integer program, the degraded modes, and a validation checklist to work through before reporting a design.
Use it from another agent (MCP)
The section above assumes an agent that has cloned this repo and can read
SKILL.md. For an agent working somewhere else, or one that cannot read a repo
at all, there is an MCP server. It presents the tool as fifteen typed tools
rather than a manual to read:
pip install ipro-agent{"mcpServers": {"ipro-agent": {"command": "ipro-agent-mcp",
"cwd": "/path/to/a/clone"}}}That block goes in your client's MCP config (Claude Desktop's config file,
.mcp.json for Claude Code, Cursor's settings; the shape is shared).
bash scripts/bootstrap.sh prints it with your own paths already filled in,
which is the easier route.
The MCP Registry lists the server as
io.github.chowdhurylab-studio/ipro-agent, which is the name to give a
client that installs from the registry instead of from a config block.
Set cwd to a checkout even when you installed with pip. The documents served
as resources (ipro://skill and the rest) ship with the repository rather than
inside the package, so a server that cannot see a checkout will list them and
then tell the agent where to fetch them instead of serving them. Use the conda
environment's python rather than a bare python3: a local server sees only what
its own interpreter can import, so the wrong one means PyMOL does not resolve
and no design can run.
Tool | What it does |
| what resolved, and whether a design is possible at all |
| create the environment, when the agent has a shell and the user says so |
| download a PDB entry by id, optionally one chain; the only networked tool |
| chains, residue span, sequence, and what residue a position number actually is |
| the five objectives and the paper each comes from |
| check a spec before spending CPU |
| propose design positions from the structure |
| measure a structure without designing |
| emit the integer program, to prove the constraints are in it |
| launch a run detached, returns a run id |
| poll it; carries the mode and the notes |
| the design itself: mutations, sequence, ensemble, and the PDB on request |
| the trajectory's tail, with the reason each iteration was rejected |
| every run this server can see, for a lost id |
| stop a running design, keeping what it has written |
ipro_fetch_structure and ipro_inspect_structure are there because a remote
agent has no shell: without them "redesign OmpF, you may change residues 18,
20, 38 and 40" cannot even be started, and a position number that is never
resolved against the structure silently designs a different residue than the
user named. Resolve the positions and say what they are before writing a spec;
docs/EXAMPLE_PROMPTS.md prompt 1 is that path end to end.
A spec can be a file path or inline YAML, since an agent usually has it in
context rather than on disk. ipro_run refuses to launch when PyMOL has not
resolved, rather than starting a job that dies at the first rotamer harvest.
It also serves the documents, so a remote agent is not worse informed than one that cloned the repo. Fifteen tool descriptions cannot carry the operating manual, so the manual is a resource instead:
Resource | |
| the full operating manual: goal selection, spec format, degraded modes, validation checklist |
| the non-negotiables, short |
| an annotated spec to copy from |
| provenance, the integer program, dependencies, scope of use, what the example can reproduce |
There are also three prompts, which clients show as slash commands:
ipro-redesign (walks the whole documented order for a new protein),
ipro-check-setup, and ipro-report (turns a finished run into an honest
report).
The server can install its own dependencies. It is pure standard library, so it
starts on a machine with nothing installed, which is the only way it can report
that nothing is installed. ipro_doctor names what is missing and ipro_setup
reports the exact command; with confirm=true it runs the conda install itself.
Measured in an empty virtualenv: the server starts, reports
missing_required: ['numpy', 'Bio', 'yaml'], finds mamba, and hands back the
command without installing anything.
One limit remains. It is a local server, so the environment it installs has to
be the one the server itself runs in: after ipro_setup finishes, point your
MCP config at that environment's python
(.../envs/ipro-agent/bin/python -m ipro_agent.mcp_server), or PyMOL still
will not resolve. ipro_setup says so in its result.
Documentation
File | Contents |
how an agent drives this tool (auto-loaded) | |
every capability traced to its paper and equation, and every deviation | |
the integer program in full | |
dependencies and what each one unlocks | |
worked case, with an | |
five prompts to paste at an agent, and what each actually produces | |
passing this to a labmate, a student or your future self |
Dependencies
Required: Python ≥ 3.10, numpy, Biopython, PyYAML, and PyMOL, which has
no fallback. Rotamers come only from its mutagenesis wizard; there is no
built-in rotamer builder, and backends.mutate: builtin is refused by the config.
Without it validate, positions and goals work; milp, score and run
do not, because all three build rotamer tables and rotamers come only from
PyMOL. Measured on a machine with no PyMOL discoverable: validate and goals
exit 0, milp and score refuse with "backend missing: no PyMOL available". conda env create -f environment.yml installs all
five.
Genuinely optional, each resolved at run time with a documented fallback:
Tool | Used for | Without it |
PyRosetta | backbone relaxation, scoring | loop runs |
AutoDock Vina | re-docking partners after mutation | input poses are kept |
MILP solver (CPLEX, Gurobi, CBC, HiGHS, GLPK) | proving the optimal packing | a heuristic that does not prove optimality |
scripts/doctor.py reports what resolved and what a run will actually use. It
also refuses an interpreter below the floor: on Python 3.9 with every
dependency installed it reports can_run: false and exits 1, because
import ipro_agent fails there whatever else is present.
Platforms: developed and tested on macOS (Apple silicon), and used on Linux.
Windows is untested. The detached-run path has a Windows branch and the
interpreter search looks in Scripts/python.exe and %USERPROFILE%, but
nothing here has ever run on Windows, PyMOL's conda package is the only
supported route to it, and a few paths assume a POSIX shell. On Windows use WSL
2, where the Linux instructions apply unchanged.
Status and honesty
This is research code and an independent reimplementation. It was written from
the published formulations; the released upstream source was read for behaviour
the papers leave ambiguous, and every value taken from it is cited as such in
docs/DESIGN.md §2 and docs/MILP.md. No upstream IPRO code is copied. It
substitutes an open stack for the original's CHARMM, GAMS/CPLEX and in-house
Monte-Carlo docking, so energies are not comparable to the numbers in the IPRO
papers, and identical designs should not be expected.
What it has actually been run on: every end-to-end run in this repo has been on one chain of PDB 2OMF, with 1CRN as a test fixture. No other protein has been tried here, and no design from this code has been synthesised or tested experimentally. The checks listed below are self-consistency checks of the optimizer rather than validation against experiment.
What has been verified here: the MILP reproduces exhaustive enumeration exactly
on a test case (including with a class-cardinality constraint), the integer cuts
provably prevent revisiting a sequence, and the Metropolis temperature
reproduces IPRO's published calibration. The PyRosetta and AutoDock Vina paths
have now been executed. Both were installed deliberately to do so, and between
them that found seven defects, because neither path had ever run
(docs/DESIGN.md §7e). What remains unexercised is listed in
ipro_agent/energy/pyrosetta_backend.UNEXERCISED, which a test keeps honest.
One known defect is open, and it can produce a wrong answer that looks right.
The channel axis is fitted through the centroid of the design positions, so it
only follows the channel when those positions ring the lumen. When they do
not, as with four positions along one wall in the shipped smoke example, the
axis runs inside the protein and the reported "bottleneck" is a gap beside a
wall, which then passes PoreDesigner's published sub-4 Å filter. The run says
so in its notes and reports the axis clearance, but any pore radius from a spec
whose positions do not surround the channel must be treated as meaningless;
give goal_options.pore_axis explicitly instead. docs/DESIGN.md §7h has the
measurements, and why the clearance has to be measured on the input structure
rather than on a candidate.
Objectives of this kind reproduce the rank and sign of a change far better than its magnitude; published hit rates for this family of methods are roughly 24–43%. Every design is a hypothesis for the bench.
Responsible use
This is a research tool that proposes mutations. It does not know what it is being pointed at, and a coding agent driving it knows even less.
Research use, on targets you are authorised to work on. Every design is a hypothesis for the bench rather than a validated construct; published hit rates for this family of methods are roughly 24–43%.
Some targets need a human in the loop before anything is run, not after the result arrives: toxins, virulence factors and select agents; anything intended to change host range, transmissibility, immune escape or drug resistance; and any sequence heading for synthesis. If the goal is to make a protein better at harming, that is not a use this repo supports.
An agent must not relax the user's stated constraints to make a failing run succeed. The troubleshooting tables offer knobs (widen
allowed, loosen a catalytic-distance restraint, raisemax_self_energy) and every one of them changes the scientific question. Report the change; do not absorb it.Report the mode and the notes with every design, a house rule in
AGENTS.md. A run in a degraded mode, or one where nothing was accepted, is not a design and must not be presented as one.Screening energies from the built-in backend are not kcal/mol comparable to the papers, and no design from this code has been tested experimentally.
Citing
For the implementation, cite this repository. CITATION.cff carries the
metadata, and GitHub's "Cite this repository" button renders it.
For the method, cite the original work. docs/DESIGN.md has the full list
with DOIs; the main entries are:
IPRO: Saraf, Moore, Goodey, Cao, Benkovic, Maranas. Biophys J 90:4167 (2006).
The IPRO suite: Pantazes, Grisewood, Li, Gifford, Maranas. J Comput Chem 36:251 (2015).
PoreDesigner: Chowdhury et al. Nat Commun 9:3661 (2018).
IPRO+/−, insertions and deletions: Chowdhury et al. Structure 28:1344 (2020).
Specificity redesign: Grisewood et al. ACS Catal 7:3837 (2017).
OptZyme: Grisewood et al. PLoS ONE 8:e75358 (2013).
Licence
MIT: see LICENSE, with the scope spelled out in NOTICE.md.
That covers this implementation only: the code, tests and documentation written here. Three things in this tree are deliberately not covered, and the licence file says so in its own words:
The method | Not ours and not licensed by us. Cite the papers above for the method and this repo only for the implementation. |
| Publisher PDFs and clones of upstream repositories, kept locally for provenance and git-ignored: they are not in this repository and are not redistributed. |
Optional dependencies | PyMOL, AutoDock Vina, Open Babel, PyRosetta and any MILP solver are separately licensed and separately installed. PyRosetta requires its own licence; see |
No upstream IPRO code is copied here. That is what makes publishing this
defensible: the upstream releases carry no LICENSE file at all, and the
Maranas group's pages describe the suite as freely available to academic users.
This is an independent reimplementation rather than a fork, written from the
papers, with the released source read only for behaviour the papers leave
ambiguous (chiefly a handful of numeric defaults); every such value is cited as
coming from the source in docs/DESIGN.md §2 and docs/MILP.md.
docs/DESIGN.md §6 maps every capability back to the paper and equation it came
from, so the provenance of each piece is checkable.
Available Tools
15 toolsipro_cancelA
Stop a running design. It stops after the iteration it is in and keeps what it has written, so the best design found so far is still readable with ipro_result. Only runs this server started, on this machine.
Inputs: run_id, run_dir.
ipro_doctorA
What is installed and what a run can therefore do. Call this FIRST: it returns can_run, can_design and the degraded backend list, and the resolved mode must be reported with any design.
Inputs: no named parameters.
ipro_fetch_structureA
Download a structure from the RCSB PDB by its four-character ID (e.g. 2OMF), optionally writing a copy reduced to one chain. This is the ONLY tool here that uses the network. Use it when the user names a protein or a PDB entry rather than giving you a file. Always check what you got with ipro_inspect_structure afterwards: resolution, missing residues and engineered mutations all change what a design means.
Inputs: pdb_id (required), out, force, chains.
ipro_goalsA
The design objectives this tool can express (bind_tighter, switch_specificity, reshape_channel, improve_catalysis, stabilize), each with the paper it comes from. Use it to pick a goal before writing a spec.
Inputs: no named parameters.
ipro_inspect_structureA
What is in a structure file: chains, residue counts and ranges, the one-letter sequence, ligands and waters -- and, for residues you name, the NATIVE identity plus a ready-to-paste spec line. Call this before writing a spec, every time. A user who says 'residues 18, 20, 38 and 40' has not said which chain, and a residue number that resolves to the wrong chain silently designs a different residue. It needs no PyMOL and no network.
Inputs: structure (required), chains, positions.
ipro_iterationsA
The tail of the trajectory: per-iteration score, whether it was accepted, and why it was rejected. The reporting rule tells you to read the per-iteration reasons, and this is how. Never read iterations.jsonl directly; it grows without limit.
Inputs: limit, run_id, run_dir, only_accepted.
ipro_milpA
Emit the rotamer-selection integer program as a CPLEX LP file and report its size. Use it to prove to a user that their stated constraints really are in the program before a long run.
Inputs: spec (required), out.
ipro_positionsB
Propose design positions from the structure: residues of the design molecule within a cutoff of a named partner, i.e. the interface or pocket. Use it when the user says 'the interface' instead of listing residue numbers.
Inputs: spec (required), near, cutoff.
ipro_resultA
The design a run produced: the mutation string, the sequence, the score change, the components, the notes, the ensemble of alternatives, and -- with include_structure -- the designed PDB itself. Report from this rather than from ipro_status alone: an MCP client has no shell, so this is the only way to hand over the coordinates. If no mutation was kept it says so, and the structure is then the starting point.
Inputs: run_id, run_dir, include_structure.
ipro_runA
Launch a design run and return immediately with a run id. The run is DETACHED and can take minutes to days, so poll ipro_status rather than waiting. Refuses to launch when a design is impossible (no PyMOL). Always pass max_minutes for an unattended run.
Inputs: spec (required), seed, run_dir, iterations, +1 more.
ipro_runsA
Every run this server can see, with its status. For when a run id has been lost, or to check what is already running before starting another.
Inputs: no named parameters.
ipro_scoreA
Measure a structure without designing anything: interaction energies per partner, the goal's score and its components, plus the run mode and notes. Use it for a wild-type baseline, or to get goal_options.reference_interaction before a constrained run.
Inputs: spec (required).
ipro_setupA
Check whether this machine can actually run a design and, with confirm=true, install what is missing. Call it when ipro_doctor reports can_design=false. PyMOL is conda-only and has no fallback, so pip cannot fix it. Installs nothing without confirm=true; tell the user what it will do first.
Inputs: confirm.
ipro_statusA
Progress of a run: iterations, how many were ACCEPTED, the best score and mutations, the mode and the notes. Cheap and bounded in size however long the run has gone on, so it is safe to poll. Never read iterations.jsonl directly -- it grows without limit.
Inputs: run_id, run_dir.
ipro_validateA
Check a design spec without spending any CPU: parses it, resolves positions against the structure, reports the design-space size and every problem found. Always do this before ipro_run.
Inputs: spec (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools occupy clearly separate slots in the workflow (doctor vs setup, fetch vs inspect, validate vs run vs cancel), and descriptions explicitly carve out boundaries such as 'never read iterations.jsonl directly' and 'report from ipro_result rather than ipro_status alone'. The only genuinely adjacent trio is ipro_status / ipro_iterations / ipro_result, where the distinction is real but relies on careful reading of the descriptions.
Every tool is namespaced with the same ipro_ prefix and uses lower snake_case, with predictable noun or verb_noun forms (ipro_fetch_structure, ipro_inspect_structure, ipro_validate, ipro_run). No mixed casing or style outliers anywhere in the set.
At 15 tools the set sits at the upper edge of the ideal band, but the count is largely earned by a multi-stage workflow: environment checks, structure acquisition/inspection, spec validation, execution, polling, cancellation, and reporting all need separate calls. A couple of members (ipro_milp, and arguably ipro_score) are niche diagnostic extras rather than core operations.
Coverage is strong end to end: readiness check, installation, structure fetch and inspection, goal selection, position proposal, validation, launch, status, per-iteration reasons, result with coordinates, run listing, and cancellation. The remaining gaps are minor housekeeping — no way to persist a spec or result to disk, and no cleanup/removal of old runs.
Maintenance
Related MCP Connectors
Design, build and run teams of AI agents with checked handoffs between them.
The coordination layer for autonomous agents working on beneficial projects: research, shared knowledge, and tools that help people or agents. Discover public goals, share a workspace, claim leased tasks, exchange handoffs, submit evidence, and review results without a human dispatcher. Agents execute in their own runtimes. Public help; OAuth or an agent key for protected tools. Start the two-agent walkthrough: https://agentsknow.app/docs/getting-started. MCP: https://agentsknow.app/mcp. Skills and examples: https://github.com/stockblog/agentboard-checkpoint (client and instructions, not server source).
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
Read a project's prompts, logs and agents, and send new work to the agent on your own machines.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that gives LLM agents access to computational protein design tools.26 PyPI19Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables protein modeling and design using the Rosetta suite via Docker, including structure refinement, mutation stability analysis, docking, and loop modeling through natural language commands.-
- AlicenseNot gradedqualityCmaintenanceEnables LLM agents to design proteins, predict structures, score interfaces, and run molecular dynamics simulations through a unified interface.1Apache 2.0
- AlicenseAqualityBmaintenanceRun real bioinformatics from your AI agent on your own GPUs: MMseqs2 homology search, ESMFold structure prediction and sequence tools for Claude, Cursor and Codex. GPU-aware scheduling for shared machines, fail-fast input checks, background jobs, agent-friendly results and provenance for every run.12Apache 2.0