get_phase_diagram

Generate phase diagrams for chemical systems to identify stable phases, formation energies, and decomposition products using Materials Project data.

Instructions

Get phase diagram data for a chemical system.

Args:
    elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)

Returns:
    JSON with phase diagram entries including stable phases, formation energies, and decomposition products

Input Schema

TableJSON Schema

Name	Required	Description	Default
`elements`	Yes

Implementation Reference

src/mcp_materials/server.py:470-546 (handler)

The main handler function for the 'get_phase_diagram' tool. It uses the Materials Project API to retrieve phase diagram data for a given list of elements, constructs a PhaseDiagram object, and returns JSON with stable and unstable phases including formation energies and decomposition information.

@mcp.tool()
def get_phase_diagram(
    elements: list[str],
) -> str:
    """
    Get phase diagram data for a chemical system.

    Args:
        elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)

    Returns:
        JSON with phase diagram entries including stable phases, formation energies, and decomposition products
    """
    has_key, key_or_error = check_api_key()
    if not has_key:
        return json.dumps({"error": key_or_error})

    try:
        from mp_api.client import MPRester
        from pymatgen.analysis.phase_diagram import PhaseDiagram

        with MPRester(key_or_error) as mpr:
            # Get all entries in the chemical system
            chemsys = "-".join(sorted(elements))
            entries = mpr.get_entries_in_chemsys(elements)

            if not entries:
                return json.dumps({
                    "error": f"No entries found for chemical system: {chemsys}",
                    "chemical_system": chemsys,
                })

            # Build phase diagram
            pd = PhaseDiagram(entries)

            # Get stable entries
            stable_entries = []
            for entry in pd.stable_entries:
                stable_entries.append({
                    "material_id": str(entry.entry_id) if hasattr(entry, 'entry_id') else None,
                    "formula": entry.composition.reduced_formula,
                    "energy_per_atom_eV": entry.energy_per_atom,
                    "formation_energy_per_atom_eV": pd.get_form_energy_per_atom(entry),
                })

            # Get unstable entries with decomposition info
            unstable_entries = []
            for entry in pd.unstable_entries:
                decomp, e_above_hull = pd.get_decomp_and_e_above_hull(entry)
                decomp_products = [p.composition.reduced_formula for p in decomp.keys()]
                unstable_entries.append({
                    "material_id": str(entry.entry_id) if hasattr(entry, 'entry_id') else None,
                    "formula": entry.composition.reduced_formula,
                    "energy_above_hull_eV": e_above_hull,
                    "decomposes_to": decomp_products,
                })

            return json.dumps({
                "chemical_system": chemsys,
                "num_elements": len(elements),
                "total_entries": len(entries),
                "stable_phases": {
                    "count": len(stable_entries),
                    "entries": stable_entries,
                },
                "unstable_phases": {
                    "count": len(unstable_entries),
                    "entries": unstable_entries[:20],  # Limit to first 20
                },
            }, indent=2)

    except ImportError:
        return json.dumps({"error": "mp-api or pymatgen not installed"})
    except Exception as e:
        return json.dumps({"error": str(e)})

src/mcp_materials/server.py:470-470 (registration)
The @mcp.tool() decorator registers the get_phase_diagram function as an MCP tool.
```
@mcp.tool()
```

src/mcp_materials/server.py:471-482 (schema)

Input schema defined by function signature (elements: list[str]) and comprehensive docstring describing parameters and return format.

def get_phase_diagram(
    elements: list[str],
) -> str:
    """
    Get phase diagram data for a chemical system.

    Args:
        elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)

    Returns:
        JSON with phase diagram entries including stable phases, formation energies, and decomposition products
    """

src/mcp_materials/server.py:30-36 (helper)

Helper function check_api_key() used by get_phase_diagram to validate Materials Project API key presence.

def check_api_key() -> tuple[bool, str]:
    """Check if API key is configured."""
    key = get_mp_api_key()
    if not key:
        return False, "MP_API_KEY environment variable not set. Get your key at https://materialsproject.org/api"
    return True, key

MCP Materials Server