Materials Project MCP, from scratch

A small, heavily commented build of a Materials Project MCP server, made to understand how MCP actually works rather than to replace the official one. You go from a bare Materials Project API call, to the same call wrapped as an MCP tool, to an agent that discovers and calls those tools on its own.

If you just want to use Materials Project from an AI client in real work, use the official server (it ships in the mp_api client, v0.46+, with ~23 tools). This repo is for learning the mechanics from the inside.

What is here

• mp_mcp_from_scratch.ipynb — the annotated, teach-along notebook. Every cell is explained: the bare API call, the FastMCP server, the low-level MCP client (including the auto-generated tool schema), and an agent driving the tools.
• mp_mcp_server.py — the standalone MCP server the notebook writes, four real tools over the live Materials Project API:
  • search_system(chemsys) — search a chemical system (e.g. "Li-Fe-O")
  • get_summary(material_id) — full property summary for an mp-id
  • find_semiconductors(min_gap, max_gap) — stable materials in a band-gap window
  • get_structure(material_id) — key crystal-structure facts

Run it

pip install -r requirements.txt
export MP_API_KEY=...        # free key from materialsproject.org

Then either open the notebook (select a Python that has mp-api), or run the server standalone:

python mp_mcp_server.py      # starts an MCP server on stdio; register it in an MCP client

The agent step in the notebook also uses a Groq key (free tier).

The point (in one line)

A tool is just a typed Python function; MCP is the standard envelope that makes it discoverable; the model does the tool selection. Once that clicks, every other server is the same recipe with different tools.

The wider MCP + Materials Project landscape

This was built alongside a survey of what already exists, all worth a look:

• Official Materials Project MCP, built into the mp_api client (v0.46+).
• benedictdebrah/materials-project-mcp — 21+ tools, Docker-deployable (Benedict Debrah, Peniel Fiawornu).
• janhq/material-project-mcp — focused on battery-material validation.
• pathintegral-institute/mcp.science — a collection of science MCP servers (incl. Materials Project and a GPAW DFT server).
• Xiangyu Yin's writeup: Building an MCP Server for the Materials Project.

Thanks

Built while learning MCP with atomcamp's Agentic AI cohort. Full write-up on Materials Decoded.

About

Ibtisam Ahmed Khan, a materials engineer working in data and AI. materialsdecoded.com · GitHub · LinkedIn