Materials Project

Materials Project API Skill

Overview

Query the Materials Project database for structures, properties, and thermodynamic data.

When to Use Materials Project vs. Other Tools

| Scenario | Recommended Tool | Why | |---|---|---| | Retrieving known crystal structures, band gaps, or phase diagrams from a curated database | Materials Project API | Fast access to DFT-computed data without running calculations | | Exploring structures when no API key is available | AFLOW / OQMD web interface | Alternative open databases with overlapping coverage | | Running custom DFT on a modified structure | ASE + VASP / CP2K / PySCF | Materials Project gives starting points, not bespoke calculations |

Key rule: Use the Materials Project API when you need experimentally or computationally validated structures and properties without running fresh quantum chemistry calculations.

Setup

export MP_API_KEY="your_key_here"

Core Capabilities

1. Query by Formula or Material ID

python scripts/query_materials.py --formula Fe2O3
python scripts/query_materials.py --material-id mp-149

2. Phase Diagrams

Generate phase diagrams for a chemical system.

python scripts/query_materials.py --chemsys Li-Fe-O --phase-diagram

Output

Results are printed as JSON to stdout. Structures can be saved as CIF files with --save-cif .

Anti-Patterns (Do Not Do These)

• Do not query Materials Project without setting MP_API_KEY. All requests will fail immediately with an authentication error.
• Do not assume a formula query returns only one structure. One formula can map to many polymorphs and oxidation states.
• Do not use energy_above_hull == 0 alone to guarantee synthesizability. It indicates thermodynamic stability in the DFT phase diagram, not kinetic accessibility.
• Do not neglect licensing and attribution. Materials Project data should be cited appropriately in publications.

Best Practices

• Batch queries when possible to reduce API round-trips.
• Filter by energy_above_hull to find stable phases; values closer to zero are more thermodynamically stable.
• Save structures as CIF with --save-cif if you plan to feed them into ASE, VASP, or visualization tools.
• When comparing computed properties across material families, be consistent about the functional and approximations used by the database version you are querying.
• For questions about the latest Materials Project API features, newly added data fields, or version-specific syntax changes, use WebFetch on https://docs.materialsproject.org/ before answering.

Common Errors and Fixes

| Error / Symptom | Likely Cause | Fix | |---|---|---| | MP_API_KEY environment variable not set | Missing API key | Export MP_API_KEY before running the script | | Connection error or timeout | Network issue or API rate limiting | Retry after a short delay or check Materials Project status page | | Empty results for a formula | No matching entries in the database | Try a different formula formatting or search by element chemsys | | ValueError during phase diagram generation | Entry mismatch or unsupported chemsys | Verify the chemsys string uses valid elements separated by hyphens | | Missing properties in response | Data field not available for that material | Check the Materials Project documentation for field availability by version |

References

• Official Documentation: https://docs.materialsproject.org/
• MPRester API Reference: https://docs.materialsproject.org/downloading-data/using-the-api/reference/
• GitHub (pymatgen): https://github.com/materialsproject/pymatgen
• GitHub (mp-api): https://github.com/materialsproject/api

Getting Live Information

If the user asks about recently added features, new data fields, or version-specific syntax changes, use WebFetch on the official documentation at https://docs.materialsproject.org/ before answering.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WuGroup-XJTLU
• Source: WuGroup-XJTLU/cc-skills-ZhenghaoWu-Group
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.