materials-project

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

• 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.