Building an MCP Server for the Materials Project

Introduction

In this blog post, I will demonstrate how to build a Model Context Protocol (MCP) server that connects to the Materials Project (MP) database. MCP is a standard for bridging AI applications (like Claude, ChatGPT, or in general any LLM-based client that supports MCP) with external data and tools. Instead of manually calling an API, you’ll expose a set of tools under a standardized protocol. This means you can seamlessly integrate these Materials Project queries into multiple AI frameworks with minimal custom code. For more details on MCP, see the official website.

A brief introduction to the Materials Project API

The Materials Project API provides programmatic access to a massive store of computed materials data: from crystal structures (CIFs), to band structures, to thermodynamic quantities like formation energy and energy above hull. The official Python client is mp_api. Typical usage (non-MCP) might look like:

from mp_api.client import MPRester

with MPRester("your_api_key_here") as mpr:
    docs = mpr.materials.summary.search(elements=["Si", "O"], band_gap=(0.5, 1.0))

Although it’s straightforward to call mp_api from your local Python environment, hooking it up to an LLM for agent-like usage typically requires additional bridging code.

Why not just call the MP API directly?

If you’re only using one AI platform or a single environment (like a Jupyter notebook), you can just call mp_api functions directly. However, this approach doesn’t scale well if you want:

1. Multiple AI apps: Tools like Cursor, Windsurf, Claude Desktop, Emacs clients, etc., all want to discover and call your “tools” in a standard, stable way.
2. One integration for many LLMs: With MCP, you write your code once. Any LLM app that supports the protocol can discover your server, see its docs, and call your exposed tools.
3. Granular permission control: The protocol ensures the user must approve a tool call if the LLM attempts to use it. This keeps you in the loop on usage.

Using MCP is especially convenient if you want to combine the Materials Project data with other advanced data sources or local resources, e.g. local quantum chemistry codes, Python scripts, or HPC job management tools. AI applications that speak MCP can chain all of them together seamlessly.

Step-by-step: The Materials Project MCP server

Below is the main code of our server (a Python script). You can see how we define two tools:

Click to expand the code

# File: materials_project_plugin.py
#
# An MCP server exposing tools for querying the Materials Project database
# via mp_api. Once running, tools can be invoked through any MCP-compatible
# client (e.g. Claude Desktop).
#
# Dependencies:
#   pip install "mcp[cli]" aiohttp pydantic mp_api 
#
# Environment:
#   MP_API_KEY=<your_materials_project_api_key>
#

import os
import logging
from typing import Optional, List
from emmet.core.electronic_structure import BSPathType
from mcp.server.fastmcp import FastMCP
from pydantic import Field

# Materials Project client
from mp_api.client import MPRester

# Setup logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("materials_project_mcp")

# Obtain your Materials Project API key from env var
API_KEY = os.environ.get("MP_API_KEY")

# Create the MCP server instance
mcp = FastMCP(
    name="Materials Project Plugin",
    version="0.0.1",
    description=(
        "A Model Context Protocol (MCP) server that exposes query tools "
        "for the Materials Project database using the mp_api client."
    ),
)


def _get_mp_rester() -> MPRester:
    """
    Helper function to initialize a MPRester session with the user's API key.
    """
    if not API_KEY:
        logger.warning(
            "No MP_API_KEY found in environment. Attempting MPRester() without key."
        )
        return MPRester()
    return MPRester(API_KEY)


@mcp.tool()
async def search_materials(
    elements: Optional[List[str]] = Field(
        default=None,
        description="List of element symbols to filter by (e.g. ['Si', 'O']).",
    ),
    band_gap_min: float = Field(
        default=0.0, description="Lower bound for band gap filtering in eV."
    ),
    band_gap_max: float = Field(
        default=10.0, description="Upper bound for band gap filtering in eV."
    ),
    is_stable: bool = Field(
        default=False,
        description="Whether to only retrieve stable materials (True) or all (False).",
    ),
    max_results: int = Field(
        default=20, ge=1, le=200, description="Maximum number of results to return."
    ),
) -> str:
    """
    Search for materials in the Materials Project database using basic filters:
    - elements (list of elements to include)
    - band_gap (range in eV)
    - is_stable
    Returns a formatted list of matches with their material_id, formula, and band gap.
    """
    logger.info("Starting search_materials query...")
    with _get_mp_rester() as mpr:
        docs = mpr.materials.summary.search(
            elements=elements,
            band_gap=(band_gap_min, band_gap_max),
            is_stable=is_stable,
            fields=["material_id", "formula_pretty", "band_gap", "energy_above_hull"],
        )

    # Truncate results to max_results
    docs = list(docs)[:max_results]

    if not docs:
        return "No materials found matching your criteria."

    results_md = (
        f"## Materials Search Results\n\n"
        f"- **Elements**: {elements or 'Any'}\n"
        f"- **Band gap range**: {band_gap_min} eV to {band_gap_max} eV\n"
        f"- **Stable only**: {is_stable}\n\n"
        f"**Showing up to {max_results} matches**\n\n"
    )
    for i, mat in enumerate(docs, 1):
        results_md += (
            f"**{i}.** ID: `{mat.material_id}` | Formula: **{mat.formula_pretty}** | "
            f"Band gap: {mat.band_gap:.3f} eV | E above hull: {mat.energy_above_hull:.3f} eV\n"
        )
    return results_md


@mcp.tool()
async def get_structure_by_id(
    material_id: str = Field(..., description="Materials Project ID (e.g. 'mp-149')")
) -> str:
    """
    Retrieve the final computed structure for a given material_id from the Materials Project.
    Returns a plain text summary of the structure (lattice, sites, formula).
    """
    logger.info(f"Fetching structure for {material_id}...")
    with _get_mp_rester() as mpr:
        # Shortcut method to get just the final structure
        structure = mpr.get_structure_by_material_id(material_id)

    if not structure:
        return f"No structure found for {material_id}."

    # Summarize the structure
    formula = structure.composition.reduced_formula
    lattice = structure.lattice
    sites_count = len(structure)
    text_summary = (
        f"## Structure for {material_id}\n\n"
        f"- **Formula**: {formula}\n"
        f"- **Lattice**:\n"
        f"   a = {lattice.a:.3f} Å, b = {lattice.b:.3f} Å, c = {lattice.c:.3f} Å\n"
        f"   α = {lattice.alpha:.2f}°, β = {lattice.beta:.2f}°, γ = {lattice.gamma:.2f}°\n"
        f"- **Number of sites**: {sites_count}\n"
        f"- **Reduced formula**: {structure.composition.reduced_formula}\n"
    )
    return text_summary


if __name__ == "__main__":
    logger.info("Starting Materials Project MCP server...")
    mcp.run()

1. search_materials: Queries the Materials Project for stable/instable materials with certain elements and band gap constraints.
2. get_structure_by_id: Retrieves the final computed crystal structure for a known material_id (like mp-149 for silicon).

When run, it starts an MCP server over STDIO. Any MCP-compatible client can spawn this script, discover the tools, and use them interactively with user approval.

What’s happening?

1. FastMCP(...): Creates a fast auto-configured server that uses standard input/output to communicate with LLM-based clients.
2. @mcp.tool(): Decorates an async function, making it discoverable by MCP clients as a “tool.”
3. search_materials: Queries for materials, filtering by band gap or stability. Returns a markdown summary.
4. get_structure_by_id: Grabs the final computed structure from the MP database and returns it in a textual summary format.
5. mcp.run(): Launches the event loop and starts listening for requests from any connected client.

Using the MCP server in Claude Desktop

As an example, we’ll show how you might connect to this server with Claude Desktop.

Step 1: Install dependencies & set environment

Make sure you have:

• A Python environment: python3 -m venv .venv then source .venv/bin/activate
  
• Packages: pip install "mcp[cli]" aiohttp pydantic mp_api

Step 2: Put the server script somewhere

For example, you put materials_project_plugin.py in ~/mcp-servers/mp_plugin/. Make sure it’s executable or that you can call python on it.

Step 3: Add to claude_desktop_config.json

Locate your Claude Desktop config. On macOS, it’s at: ~/Library/Application Support/Claude/claude_desktop_config.json. For Windows, check: %APPDATA%\Claude\claude_desktop_config.json

Add a snippet like this:

{
  "mcpServers": {
    "materials_project_plugin": {
      "command": "/ABSOLUTE/PATH/TO/python/executable",
      "args": [
        "/ABSOLUTE/PATH/TO/mp_plugin/materials_project_plugin.py"
      ],
      "env": {
        "MP_API_KEY": "<YOUR_MATERIALS_PROJECT_API_KEY>"
      }
    }
  }
}

Step 4: Restart Claude Desktop

Claude will now spawn the plugin automatically. You should see a new hammer icon in your chat window, representing available MCP tools.

Claude Desktop Showing MCP Server Tools

Step 5: Test queries

Here is an example prompt you can try:

> I'm researching materials for solar cell applications. Can you:
> 1) Find me 5 stable semiconductor materials with band gaps between 1.0 and 2.0 eV 
>    that contain either Ga, or In?
> 2) For the most promising candidate (lowest energy above hull), retrieve and explain 
>    its crystal structure.

Claude will use the “search_materials” tool with your provided constraints, then possibly call “get_structure_by_id” to retrieve further details. Below is a sample snippet from the conversation output:

Example of a conversation with Claude Desktop and the MCP server

Wrap-up and additional links

That’s it! You now have an MCP server that can call Materials Project queries. You can start from this basic example and adapt it to your needs by:

• Experiment with advanced queries (like stable phases in multi-element chemical systems).
• Add or refine tools in your server for more specialized searches (e.g., stable doping compositions).
• Combine with other servers in your environment, for a multi-functional AI agent.

Tip

Enjoy exploring materials data with your new AI-savvy pipeline!😊