compare_materials

Compare properties of multiple materials side by side to analyze differences and identify optimal selections for specific applications.

Instructions

Compare properties of multiple materials side by side.

Args:
    material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])

Returns:
    JSON table comparing key properties across materials

Input Schema

TableJSON Schema

Name	Required	Description	Default
`material_ids`	Yes

Implementation Reference

src/mcp_materials/server.py:210-262 (handler)

The core handler function for the 'compare_materials' tool. It fetches material summaries from Materials Project API using MPRester, compares key properties like formula, band gap, stability, etc., and returns a JSON-formatted comparison table. Includes error handling for invalid IDs and API issues.

@mcp.tool()
def compare_materials(
    material_ids: list[str],
) -> str:
    """
    Compare properties of multiple materials side by side.

    Args:
        material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])

    Returns:
        JSON table comparing key properties across materials
    """
    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

        comparison = []

        with MPRester(key_or_error) as mpr:
            for mid in material_ids:
                try:
                    doc = mpr.materials.summary.get_data_by_id(mid)
                    crystal_system = None
                    if doc.symmetry and doc.symmetry.crystal_system:
                        crystal_system = str(doc.symmetry.crystal_system.value) if hasattr(doc.symmetry.crystal_system, 'value') else str(doc.symmetry.crystal_system)
                    comparison.append({
                        "material_id": str(doc.material_id),
                        "formula": doc.formula_pretty,
                        "band_gap_eV": doc.band_gap,
                        "formation_energy_eV": doc.formation_energy_per_atom,
                        "energy_above_hull_eV": doc.energy_above_hull,
                        "density_g_cm3": doc.density,
                        "is_stable": doc.is_stable,
                        "is_metal": doc.is_metal,
                        "crystal_system": crystal_system,
                    })
                except Exception as e:
                    comparison.append({
                        "material_id": mid,
                        "error": str(e),
                    })

        return json.dumps({
            "count": len(comparison),
            "comparison": comparison,
        }, indent=2)

    except Exception as e:
        return json.dumps({"error": str(e)})

src/mcp_materials/server.py:210-210 (registration)
The @mcp.tool() decorator registers the compare_materials function as an MCP tool, automatically generating schema from type hints and docstring.
```
@mcp.tool()
```

src/mcp_materials/server.py:211-222 (schema)

Input schema defined by type hint 'material_ids: list[str]' and comprehensive docstring describing parameters and return format (JSON comparison table).

def compare_materials(
    material_ids: list[str],
) -> str:
    """
    Compare properties of multiple materials side by side.

    Args:
        material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])

    Returns:
        JSON table comparing key properties across materials
    """

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

Shared helper function used by compare_materials (and other tools) to validate Materials Project API key presence before making API calls.

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

src/mcp_materials/server.py:829-831 (registration)
The main() function initializes and runs the FastMCP server instance (created at line 19), which scans and registers all @mcp.tool() decorated functions including compare_materials.
```
def main():
    """Run the MCP server."""
    mcp.run()
```

MCP Materials Server