# 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

```bash
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:

```bash
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](https://github.com/benedictdebrah/materials-project-mcp) — 21+ tools, Docker-deployable (Benedict Debrah, Peniel Fiawornu).
- [janhq/material-project-mcp](https://github.com/janhq/material-project-mcp) — focused on battery-material validation.
- [pathintegral-institute/mcp.science](https://github.com/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](https://xiangyu-yin.com/content/post_mp_mcp.html).

## Thanks

Built while learning MCP with **atomcamp**'s Agentic AI cohort. Full write-up on
[Materials Decoded](https://materialsdecoded.com).

## About

Ibtisam Ahmed Khan, a materials engineer working in data and AI.
[materialsdecoded.com](https://materialsdecoded.com) ·
[GitHub](https://github.com/ibtisamkhan96) ·
[LinkedIn](https://www.linkedin.com/in/ibtisam-ahmed-khan)