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 featherflow / Claude Desktop)

python -m mofstructure.mcp_server
# or, after pip install:
mofstructure_mcp

featherflow integration

Edit ~/.featherflow/config.json:

{
  "tools": {
    "mcpServers": {
      "mofstructure": {
        "command": "/path/to/mofstructure/.venv/bin/python",
        "args": ["-m", "mofstructure.mcp_server"],
        "toolTimeout": 120
      },
      "mofchecker": {
        "command": "/path/to/mofchecker/.venv/bin/python",
        "args": ["-m", "mofchecker.mcp_server"],
        "toolTimeout": 120
      },
      "zeopp": {
        "url": "http://localhost:9877/mcp",
        "toolTimeout": 120
      }
    }
  }
}

On Windows replace the path with C:/path/to/mofstructure/.venv/Scripts/python.exe.

Using as a Python library

The library API is unchanged from the original:

from mofstructure import structure

mof = structure.MOFstructure(filename="path/to/your.cif")

# Remove guest molecules
clean = mof.remove_guest()

# Deconstruct into SBUs  (cheminfo=True computes SMILES / InChI / InChIKey)
metal_sbus, organic_sbus = mof.get_sbu(cheminfo=True)
for sbu in metal_sbus:
    print(sbu.info['sbu_type'], sbu.info['smi'])

# Deconstruct into ligands and metal clusters
metal_clusters, organic_ligands = mof.get_ligands(cheminfo=True)
for ligand in organic_ligands:
    print(ligand.info['inchikey'])

Command-line tools

| Command | Description | |---|---| | mofstructure <cif_file> [output_dir] | Deconstruct a single CIF into SBUs and ligands | | mofstructure_database <cif_folder> [output_dir] | Batch-process a folder of CIFs into a database | | mofstructure_building_units <cif_folder> | Batch deconstruction only | | mofstructure_curate <cif_folder> | Curate / validate a folder of CIFs | | mofstructure_mcp | Start the MCP server (stdio) |

License

MIT — same as the original project.