mofstructure — MCP Edition
A lean, MCP-enabled repackaging of the outstanding mofstructure library by Dr. Dinga Wonanke.
Standing on the shoulders of giants
Let's be blunt: the original mofstructure is one of the most impressive pieces of
software in computational materials science written by a single researcher.
In a field where "framework analysis" usually means running a black-box binary and
hoping the output makes sense, Dr. Wonanke built something genuinely different.
The deconstruction engine inside mofdeconstructor.py — over 2 000 lines of
carefully reasoned graph theory — can take any arbitrary MOF crystal structure and
correctly identify every secondary building unit, every organic ligand, every metal
cluster, the SBU topology, the coordination number of every metal centre, and the
points of extension — all automatically, all in pure Python, without ever needing
a pre-curated database of known topologies to look things up in.
That is a hard problem. Most tools either require you to label things manually, rely
on heuristic pattern matching that breaks on anything non-standard, or are proprietary
closed-source binaries. mofstructure does it right: it constructs the full molecular
graph, identifies metal nodes, finds the organic bridges, locates the breaking points,
and assembles the building units — then hands you back proper ASE Atoms objects with
SMILES, InChI and InChIKey already computed via OpenBabel.
The guest-removal logic is similarly thoughtful. Rather than a naive "delete small molecules" heuristic it analyses graph connectivity to find genuinely unbound components, which means it works correctly even on unusual solvates and disordered structures that trip up simpler approaches.
And the COF stacking analysis, the PBC wrapping, the IUPAC name lookup database — all of it is the kind of infrastructure that takes years of domain knowledge to build correctly.
If you are doing any serious high-throughput MOF screening or computational reticular chemistry, reading the original codebase is essential. This fork would not exist without its extraordinary foundation.
Original repository: https://github.com/bafgreat/mofstructure
Original author: Dr. Dinga Wonanke — https://www.dingawonanke.com
Original paper: Wonanke et al., Journal of Open Source Software, 2024.
What is this fork?
This edition strips the original down to a focused MCP (Model Context Protocol) server so that AI agents — in particular those built with featherflow — can call MOF structure operations as tools over stdio or HTTP.
What was removed and why
| Removed | Reason |
|---|---|
Porosity calculation (porosity.py) |
Provided by the separate zeopp-backend MCP service |
Open metal site detection (get_oms) |
Provided by mofchecker-mcp and zeopp-backend |
obsolate/ directory |
Dead code, superseded by current implementation |
| Sphinx docs | Out of date; not needed for MCP deployment |
What was added
| Added | Description |
|---|---|
mofstructure/mcp_server.py |
FastMCP server exposing 5 tools over stdio |
mcp dependency |
MCP Python SDK |
mofstructure_mcp CLI entry point |
python -m mofstructure.mcp_server |
The three-service architecture
This fork is designed to work alongside two companion MCP services:
mofchecker-mcp → "Is this structure valid?" (quality checks)
mofstructure-mcp → "What is this structure made of?" (deconstruction + cleanup)
zeopp-backend → "How porous is this structure?" (geometric analysis)
Point your agent at all three and it can perform end-to-end MOF analysis from a raw CIF file.
Installation
Important — each MCP server should run in its own virtual environment.
git clone https://github.com/lichman0405/mofstructure.git
cd mofstructure
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
pip install -e .
Optional RDKit support:
pip install -e ".[rdkit]"
MCP tools
The server exposes five tools. Every tool accepts either a cif_path (absolute path
on the server filesystem) or cif_content (raw CIF text).
| Tool | Description |
|---|---|
remove_guest |
Remove unbound guest molecules; returns clean host CIF |
get_sbu |
Deconstruct into metal + organic SBUs with SMILES / InChI / InChIKey |
get_ligands |
Deconstruct into metal clusters + organic ligands with cheminformatics |
wrap_structure |
Wrap atoms into unit cell — fixes the "broken bond" PBC visualisation artefact |
analyze_cof_stacking |
Compute interlayer lateral offsets and heights; classify AA / AB / mixed stacking |
Running the server
stdio (for
Tools 5
remove_guestRemove unbound guest molecules from a CIF structure and return the clean host CIF.get_sbuDeconstruct a MOF into metal and organic SBUs with computed SMILES, InChI, and InChIKey.get_ligandsDeconstruct a MOF into metal clusters and organic ligands with cheminformatics data.wrap_structureWrap atoms into the unit cell to fix PBC visualisation artefacts.analyze_cof_stackingCompute interlayer lateral offsets and heights to classify AA, AB, or mixed stacking.