| name | materials-project |
| description | Use when querying the Materials Project database for crystal structures, material properties, or generating phase diagrams. Requires the MP_API_KEY environment variable to be set. |
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 <dir>.
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
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.
