MCP Materials Server

How to use

Interact with the server using an MCP client to perform practical material science tasks. You can search for materials by formula, fetch crystal structures in common formats, retrieve comprehensive properties, compare multiple materials, and run advanced analyses such as phase diagrams and elastic properties. Use the client to compose queries like requesting the properties of a specific material ID, finding materials containing particular elements, or filtering results by band gap or elastic moduli.

How to install

Prerequisites: You need Python 3.11 or higher. You also require a Materials Project API key to access data.

Steps to set up the server locally:

Create and activate a virtual environment, install the package in editable mode, and prepare your API key.

Install and run steps

# Create and move into the project directory
# (clone or navigate to the project)

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install the package in editable mode
pip install -e ".[dev]"

Set your Materials Project API key in your environment for the server to access data.

# On Windows (PowerShell):
$env:MP_API_KEY = "your_api_key_here"

# On Windows (CMD):
set MP_API_KEY=your_api_key_here

# On macOS/Linux:
export MP_API_KEY="your_api_key_here"

Run the server either via the installed entry point or directly using Python.

# Using the installed command
mcp-materials

# Or run directly
python -m mcp_materials.server

Configuration for clients like Claude Desktop

To connect Claude Desktop to the MCP Materials Server, add a server configuration that runs the server locally and passes your API key. This preserves a seamless workflow from Claude to the materials data.

{
  "mcpServers": {
    "materials": {
      "command": "python",
      "args": ["-m", "mcp_materials.server"],
      "cwd": "D:\\path\\to\\mcp-materials-server",
      "env": {
        "MP_API_KEY": "your_api_key_here"
      }
    }
  }
}

Example queries you can perform after connection

Basic searches like finding materials by formula or elements, and advanced analyses like phase diagrams or elastic properties, are supported through your MCP client.

Common workflows include asking for a material’s properties, comparing multiple materials side-by-side, and generating a phase diagram for a given chemical system.

Notes on usage and capabilities

This server exposes a set of tools to interact with materials data. You can search by formula, retrieve structures in CIF/POSCAR/JSON formats, obtain full properties, perform material comparisons, and run analyses such as phase diagrams and elastic property lookups.

Development and testing

If you are contributing or testing locally, you can run the test suite with pytest and lint the code with ruff. Ensure your environment has the required dependencies and that your API key is configured for data access.

Project structure and tools overview

The server provides a set of 10 tools and 2 resources to help you work with materials data. The tools include searching materials by formula, retrieving structures, getting properties, comparing materials, and more advanced queries like searching by band gap, similar structures, and phase diagrams.

search_materials

Search materials by chemical formula and return matching material IDs with basic data such as band gaps, formation energies, and stability information.

get_structure

Retrieve crystal structure in CIF, POSCAR, or JSON format for a given material ID.

get_properties

Obtain a full set of properties for a material, including composition, symmetry, electronic, and thermodynamic data.

compare_materials

Compare multiple materials side-by-side to evaluate differences in properties and structures.

search_by_elements

Find materials containing or excluding specific elements.

search_by_band_gap

Search materials within a band gap range, with options to filter direct gaps.

get_similar_structures

Identify materials with similar crystal structures.

get_phase_diagram

Build a phase diagram for a chemical system showing stable and decomposition products.

get_elastic_properties

Retrieve mechanical properties such as bulk modulus, shear modulus, Poisson ratio, and Debye temperature.

search_by_elastic_properties

Filter materials by ranges of elastic properties like bulk and shear modulus.