home / mcp / materials project mcp server

Materials Project MCP Server

Provides a programmatic interface to query the Materials Project database via the mp_api client.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "benedictdebrah-materials-project-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MP_API_KEY=your-api-key",
        "benedict2002/materials-project-mcp"
      ],
      "env": {
        "MP_API_KEY": "your-api-key"
      }
    }
  }
}

You can run the Materials Project MCP server to query the Materials Project database from your MCP client. It connects to the Materials Project API and exposes a set of tools that let you search materials, fetch structures, plot band structures, and more from your own environment or editor workflows.

How to use

Use an MCP client to connect to the Materials Project MCP server and run queries against the Materials Project database. You will authenticate with your Materials Project API key, then send requests to available tools such as searching materials, retrieving structures, calculating properties, and visualizing results. Start by choosing a connection method that fits your workflow, then query the available endpoints to explore materials data.

How to install

Prerequisites you need before installing the server are a Materials Project API key, Docker Desktop (running), and Python 3.12+ with uv support.

# Step A: Ensure you have a Materials Project API key
# Step B: Install Docker Desktop and ensure it is running
# Step C: Run the MCP server using the Docker image

docker pull benedict2002/materials-project-mcp

docker run --rm -i -e MP_API_KEY="your-api-key" benedict2002/materials-project-mcp

Additional setup options

You can also run the server with Docker Compose for persistent, background operation. Define your environment variable and start the services with docker-compose, then manage the service lifecycle with standard docker-compose commands.

# docker-compose.yml (example excerpt)
version: '3.8'
services:
  materials-project-mcp:
    image: benedict2002/materials-project-mcp
    environment:
      - MP_API_KEY=your-materials-project-api-key

Configuration and environment

Configure how you connect from your MCP client by providing your API key securely in the environment. Do not share your API key and rotate it if you suspect it has been compromised.

If you need to test or run locally, you can also use a local Python setup with uv to launch the server directly after cloning the repository and installing dependencies. The exact steps shown below illustrate a typical flow.

Troubleshooting and tips

Common issues include an invalid API key, Docker not running, or the MCP server not starting as expected. Ensure your API key is correct, Docker Desktop is running, and the chosen command is accessible from your shell.

For interactive testing, you can start a developer MCP inspector to verify the server is responding to queries.

Tools and capabilities

The Materials Project MCP server provides a range of tools to access materials data, including searching materials, retrieving structures and lattices, plotting band structures, density of states, phonon properties, thermodynamic data, and more.

Available tools

search_materials

Search materials by elements, band gap range, and stability.

get_structure_by_id

Retrieve crystal structures and lattice parameters by material ID.

get_electronic_bandstructure

Plot electronic band structures for a material.

get_electronic_dos_by_id

Fetch electronic density of states for a material.

get_phonon_bandstructure

Plot phonon band structures.

get_phonon_dos_by_id

Get phonon density of states.

get_ion_reference_data_for_chemsys

Download aqueous ion reference data for Pourbaix diagrams.

get_cohesive_energy

Calculate cohesive energies.

get_atom_reference_data

Retrieve reference energies of isolated neutral atoms.

get_magnetic_data_by_id

Obtain magnetic properties and ordering information.

get_charge_density_by_id

Access charge density data.

get_dielectric_data_by_id

Retrieve dielectric constants and related properties.

get_diffraction_patterns

Provide X-ray and neutron diffraction patterns.

get_xRay_absorption_spectra

Provide XAFS, XANES, EXAFS spectra.

get_elastic_constants

Return mechanical properties such as elastic constants.

get_suggested_substrates

Suggest substrates for thin films.

get_thermo_stability

Analyze thermodynamic stability.

get_surface_properties

Compute surface energies, work functions, and Wulff shapes.

get_grain_boundaries

Compute grain boundaries for a material.

get_insertion_electrodes

Provide insertion electrode and battery data.

get_oxidation_states

Provide oxidation states, formula, and structure information.